Differences between revisions 1 and 2
Revision 1 as of 2009-02-14 18:20:32
Size: 13776
Editor: eSyr
Comment:
Revision 2 as of 2009-02-14 19:00:10
Size: 21561
Editor: eSyr
Comment:
Deletions are marked like this. Additions are marked like this.
Line 15: Line 15:
Курсы были представлены в виде наборов модулей (частей), в результате чего оказалось, что имеется ненулевое их (модулей) пересечение. В итоге, для уменьшения количества работ кажды курс был представлен как набор модулей, и дальше работа происходила уже над ними (и не подразумевала написание цельных независимых курсов). Курсы были представлены в виде наборов модулей (частей), в результате чего оказалось, что имеется ненулевое их (модулей) пересечение. В итоге, для уменьшения количества работ каждый курс был представлен как набор модулей, и дальше работа происходила уже над ними (и не подразумевала написание цельных независимых курсов).
Line 17: Line 17:
Рабочий процесс был разбит на следуюшие части: Рабочий процесс был разбит на следующие части:
Line 46: Line 46:
 * Содержательное редактирование проводилось того, когда было решено, что тот или иной фрагмент лекции стоит дополнить или изменить (достаточно редкая ситуаця, обычно — оба раза — возникавшая из-за недостатка времени на демострацию примеров)
 * Организация процесса сводилась к своевремменому размещению материалов и назначению ответственных согластно их текущей загруженности (как внутри проекта, так и вне его), а также к отслеживанию задержек по выполнению тех или иных этапов работ (эта работа в последствии была частично автоматизирована, http://uneex.ru/PspoClasses/Status?action=AttachFile&do=view&target=status.sh)
 * Содержательное редактирование проводилось того, когда было решено, что тот или иной фрагмент лекции стоит дополнить или изменить (достаточно редкая ситуация, обычно — оба раза — возникавшая из-за недостатка времени на демонстрацию примеров)
 * Организация процесса сводилась к своевременному размещению материалов и назначению ответственных согласно их текущей загруженности (как внутри проекта, так и вне его), а также к отслеживанию задержек по выполнению тех или иных этапов работ (эта работа в последствии была частично автоматизирована, http://uneex.ru/PspoClasses/Status?action=AttachFile&do=view&target=status.sh)
Line 60: Line 60:
 * Материалы могут быть из различных источников и иметь различный формат. Т. о., материалом являются, например, описанные выше лекции. Также, среди материалов присутствуют нектороая часть документации ALT Linux, книги, howto, rfc, иллюстрация, статья в википедии и прочее. Среди основных видов материалов можно выделить:  * Материалы могут быть из различных источников и иметь различный формат. Т. о., материалом являются, например, описанные выше лекции. Также, среди материалов присутствуют нектороая часть документации ALT Linux, книги, howto, rfc, иллюстрация, статья в Wikipedia и прочее. Среди основных видов материалов можно выделить:
Line 69: Line 69:
 * Материалы добавляют (и оформлояют паспорт) ответственные за работу над модулем в случае необходимости (на последнем этапе для наполнения модулей в основном использовались уже имеющиеся материалы, так как накопленный их корпус покрывал курсы чуть менее, чем полностью)  * Материалы добавляют (и оформляют паспорт) ответственные за работу над модулем в случае необходимости (на последнем этапе для наполнения модулей в основном использовались уже имеющиеся материалы, так как накопленный их корпус покрывал курсы чуть менее, чем полностью)
Line 72: Line 72:
 * Ответственный, назначенный исполниетелем по данному модулю, подбирает набор материалов, покрывающих лекционный минимум, после чего формирует итоговый текст, используя собранные материалы, и, при необходимости, комментируя их (см., например, http://uneex.ru/PspoModules/FreeLicense — в виду специфики предмета потребовались обширные комментарии. Другой пример: http://uneex.ru/PspoModules/MigrationUser — содержание модуля компактно покрыто материалами лекций)  * Ответственный, назначенный исполнителем по данному модулю, подбирает набор материалов, покрывающих лекционный минимум, после чего формирует итоговый текст, используя собранные материалы, и, при необходимости, комментируя их (см., например, http://uneex.ru/PspoModules/FreeLicense — в виду специфики предмета потребовались обширные комментарии. Другой пример: http://uneex.ru/PspoModules/MigrationUser — содержание модуля компактно покрыто материалами лекций)
Line 81: Line 81:
==== Общая теория расширения функциональности MoinMoin ====
 * В MoinMoin предусмотрено несколько механизмов расширения имеющейся функциональности. Среди них можно выделить ''макросы'', ''действия'' и ''парсеры''
 * В плане реализации все три перечисленных механизма представляют из себя модули на языке Python, подгружаемые в процессе работы wiki-сервера при необходимости
 * Расширения имеют простой и прозрачный доступ ко внутренним API MoinMoin (в частности, большинство полезных в процессе разработки расширений сущностецй собрано в пакете `MoinMoin.util`)
  * Макросы (macros) вызываются при нахождении их в тексте wiki-страницы парсером в процессе её рендеринга. При этом текст вызова макроса (например, `<<PassportLink(MaterialName)>>`) заменяется на результат возвращённый макросом. Таким образом, макросы позволяют использовать в страницах на wiki-разметке дополнительную функциональность
  * Действия (actions) выполняются при обращении к wiki-серверу с соответствующим HTTP-запросом (в параметре запроса указывается имя вызываемого действия: `wikiname/Page?action=ActionName`). Результат, возвращаемый действием, возвращается как результат HTTP-запроса
  * Парсеры (parsers) предназначены для обработки самостоятельных текстов на различных языках (например, рендеринг HTML, рендеринг графов, описанных на языке dot, и так далее)
 * В случае необходимости расширения функциональности необходимо учитывать следующее:
  * Расширения wiki-синтаксиса реализуются в виде макросов (например, http://uneex.ru/eSyr/WikiHack/Macros/PassportLink)
  * При расширении функциональности помимо написания собственно действия необходимо предоставить пользовательский интерфейс к нему. Обычно это выполняется в виде соответствующего макроса (например, макрос http://uneex.ru/eSyr/WikiHack/Macros/MaterialFiles для использования соответствующего действия http://uneex.ru/eSyr/WikiHack/Actions/MaterialFiles) или изменения темы wiki.
Line 82: Line 92:
==== Организация процесса обработки фрагментов лекций ====
 * В процессе выполнения того или иного вида работ необходимо отслеживать её статус.
 * Отслеживать состояние больших кусков работ (например, состояние курса) на основании состояния маленьких.
 * Эти возможности были реализованы в рамках макроса !ExtractModules, который агрегировал таблицы специального вида с указанного списка страниц и рассчитывал по ним статистику (сколько сделано и когда это закончится)
  * Требование к организации процесса — поддерживать формат таблички и своевременно её обновлять (это прописано в полиси, см., например, http://uneex.ru/PSPO/Policy/Lections)

==== Хранение иерархии файлов, связанной с определённой страницей ====
 * В процессе работы с материалами необходимо было хранить для каждого материала дерево файлов, в него входящих. На данный момент MoinMoin не предоставляет такой возможности.
 * Необходимая функциональность была реализована в виде действия !MaterialFiles (http://uneex.ru/eSyr/WikiHack/Actions/MaterialFiles) и одноимённого макроса, предоставлявшего к нему пользовательский интерфейс (http://uneex.ru/eSyr/WikiHack/Macros/MaterialFiles)
 * Пример использования можно пронаблюдать на любой странице паспорта материала (http://uneex.ru/PspoMaterials)
 * Требование к организации процесса — при необходимости использования функциональности действия необходимо разместить макрос в тексте страницы
 * Возможно, более правильным с архитектурной точки зрения было бы реализовывать необходимую функциональность путём модификации имеюшегося макроса !AttachFile, но на момент разработки это было признано нецелесообразным

==== Полезные мелочи ====
 * Для удобства формирования паспорта были созданы пара макрос/действие (http://uneex.ru/eSyr/WikiHack/Macros/CreateMaterialPassport / http://uneex.ru/eSyr/WikiHack/Actions/CreateMaterialPassport), которые позволяли его создавать путём заполнения формы, в результате чего на основании имеющегося шаблона генерировалась страница паспорта. Пример макроса можно пронаблюдать на странице со списком материалов (http://uneex.ru/PspoMaterials)
 * Для удобства формирования информации о формате и лицензии были написаны небольшие макросы (http://uneex.ru/eSyr/WikiHack/Macros/FormatInfo, http://uneex.ru/eSyr/WikiHack/Macros/LicenseInfo), которые вставляли текст описания того или иного формата/лицензии по его названию. Описания брались с соответствующих страниц.
 * Для удобочитаемости ссылок на материалы был написан макрос !PassportLink (http://uneex.ru/eSyr/WikiHack/Macros/PassportLink), который использовал информацию со страницы паспорта (название, формат) для формирования текста ссылки (и иконки для неё)
Line 94: Line 121:
Приятная неожиданность: отчуждаемость контента, в т. ч. в виде автономного www-сервера на CD. Приятная неожиданность: отчуждаемость контента, в т. ч. в виде автономного www-сервера на CD (реализовано в виде небольшого скрипта на shell, http://uneex.ru/UneexStandalone).

Проблемы и методы командной разработки свободных учебных материалов

Ключевые слова: ПСПО, СПО, документация, командная разработка, учебный материал, wiki

Приведена история создания рабочей группы по документированию ПСПО, организация процесса создания учебного материала, структура получившегося продукта и поддерживающей его технологии. Делается попытка истолкования положительных и отрицательных результатов работы и обобщения полученного опыта.

Тезисный план

Постановка частной задачи

  • Немного истории пилотного внедрения ПСПО в российских школах.
  • Одна из задач: обучение взрослых (учителей, в т. ч. предметников, администраторов, директоров и пр.).
  • Непосредственная задача: 10 отчуждаемых курсов.

Организация рабочего процесса

Курсы были представлены в виде наборов модулей (частей), в результате чего оказалось, что имеется ненулевое их (модулей) пересечение. В итоге, для уменьшения количества работ каждый курс был представлен как набор модулей, и дальше работа происходила уже над ними (и не подразумевала написание цельных независимых курсов).

Рабочий процесс был разбит на следующие части:

  • Подготовка новых материалов (Also Sprach Zaratustra)
  • Подготовка модулей
  • Подготовка имеющихся материалов
  • Наполнение модулей

Далее, организация процесса работ включала в себя следующее:

  • Формирование полиси (http://uneex.ru/PSPO/Policy)

  • Подготовка технической базы (использование wiki (MoinMoin) с дополнительным программированием и установленной дисциплиной работы.)

  • Распределение работ по участникам
  • Отслеживание состояния работ

Подготовка новых материалов (Also Sprach Zaratustra)

  1. "Лекции" (16 ак. ч. в неделю)
  2. Конспектирование online
    • критерий качества: не упускать ключевых моментов лекции
    • Генерирование демонстрационных материалов (скриншоты, скрипты, логи). В последствии эти материалы интегрировались в текст фрагмента на этапе расшифровки
  3. "Расшифровка": воссоздание структуры лекции
    • условие: расшифровщик присутствует на лекции
    • критерий качества: "переводчику" должно быть понятно, даже если он не был на лекции
  4. "Перевод на русский"
    • критерий качества: не потерять в процессе литредактуры значимых утверждений и формулировок
  5. "Научное редактирование"
    • критерий качества: связность конечного текста
  • За каждый фрагмент отвечает конкретный исполнитель каждого этапа (http://uneex.ru/PspoClasses/Status).

  • Каждый из участников имел свою специализацию в силу собственных качеств и занимался только определённым видом работ (http://uneex.ru/PspoTasks).

Содержательное редактирование сведено к минимуму (иногда с небольшой потерей качества), организаторская работа и т .п.

  • Содержательное редактирование проводилось того, когда было решено, что тот или иной фрагмент лекции стоит дополнить или изменить (достаточно редкая ситуация, обычно — оба раза — возникавшая из-за недостатка времени на демонстрацию примеров)
  • Организация процесса сводилась к своевременному размещению материалов и назначению ответственных согласно их текущей загруженности (как внутри проекта, так и вне его), а также к отслеживанию задержек по выполнению тех или иных этапов работ (эта работа в последствии была частично автоматизирована, http://uneex.ru/PspoClasses/Status?action=AttachFile&do=view&target=status.sh)

Наполнение курсов материалами (подготовка модулей)

  • Каждый модуль состоит из лекционного минимума -- развёрнутого тематического плана будущего фрагмента курса (модуля) и итогового текста, представляющего из себя лекционный минимум, дополненный ссылками на материалы, и, при необходимости, комментариями.

  • Архитектор составляет "Лекционный минимум"
  • За каждый модуль отвечает конкретный исполнитель
    • Критерий выбора исполнителя: тема, освещаемая в модуле, ему отностильено близка
  • Исполнитель из команды подбирает ссылки на материалы, содержащие информацию по каждой теме
    • Критерий качества: покрытие материалами всего лекционного минимума, желательно, из разнородных источников (например, лекции и документация ALT Linux) (http://uneex.ru/PSPO/Policy/Modules)

  • Все использованные внешние материалы импортируются (см. далее)

Подготовка имеющихся материалов

  • Материал, некий документ, несущий некую информацию в рамках курсов
  • Материалы могут быть из различных источников и иметь различный формат. Т. о., материалом являются, например, описанные выше лекции. Также, среди материалов присутствуют нектороая часть документации ALT Linux, книги, howto, rfc, иллюстрация, статья в Wikipedia и прочее. Среди основных видов материалов можно выделить:
    • Текст в wiki-разметке (обрабатываемый собственно wiki-движком), просматриваемый в браузере
    • HTML-дерево, которое также просматривается в браузере
    • Файлы различных форматов, просматриваемые сторонними программами, внешними по отношение к браузеру
  • В виду необходимости отчуждаемости итоговой работы все материалы должны быть проимпортированы (положены в рабочее дерево материалов) и снабжены идентификационной и описательной информацией — паспортом (список всех материалов: http://uneex.ru/PspoMaterials). В паспорт включаются следующие аспекты материала:

    • Его название, авторство и источник
    • Формат материала (wiki, HTML, ODT, PDF, ...) (http://uneex.ru/PspoMaterials/FormatInfo)

    • Лицензия, под которой распространяется материал. В рамках проекта использовались материалы только под свободными лицензиями. (http://uneex.ru/PspoMaterials/LicenseInfo)

    • Аннотация (если есть)
  • Материалы добавляют (и оформляют паспорт) ответственные за работу над модулем в случае необходимости (на последнем этапе для наполнения модулей в основном использовались уже имеющиеся материалы, так как накопленный их корпус покрывал курсы чуть менее, чем полностью)

Наполнение модулей

  • Ответственный, назначенный исполнителем по данному модулю, подбирает набор материалов, покрывающих лекционный минимум, после чего формирует итоговый текст, используя собранные материалы, и, при необходимости, комментируя их (см., например, http://uneex.ru/PspoModules/FreeLicense — в виду специфики предмета потребовались обширные комментарии. Другой пример: http://uneex.ru/PspoModules/MigrationUser — содержание модуля компактно покрыто материалами лекций)

Использование MoinMoin

  • В качестве технологической базы для совместной подготовки использовался wiki-движок MoinMoin, написанный на языке Python

  • Для поддержки различных организационных аспектов в ряде случаев потребовалось незначительное расширение его функциональности.
    • Организация процесса обработки фрагментов лекций
    • Хранение иерархии файлов, связанной с определённой страницей
    • Создание ссылок на сущности различного вида, и формирование текста ссылки в зависимости от содержимого сущности

Общая теория расширения функциональности MoinMoin

  • В MoinMoin предусмотрено несколько механизмов расширения имеющейся функциональности. Среди них можно выделить макросы, действия и парсеры

  • В плане реализации все три перечисленных механизма представляют из себя модули на языке Python, подгружаемые в процессе работы wiki-сервера при необходимости
  • Расширения имеют простой и прозрачный доступ ко внутренним API MoinMoin (в частности, большинство полезных в процессе разработки расширений сущностецй собрано в пакете MoinMoin.util)

    • Макросы (macros) вызываются при нахождении их в тексте wiki-страницы парсером в процессе её рендеринга. При этом текст вызова макроса (например, <<PassportLink(MaterialName)>>) заменяется на результат возвращённый макросом. Таким образом, макросы позволяют использовать в страницах на wiki-разметке дополнительную функциональность

    • Действия (actions) выполняются при обращении к wiki-серверу с соответствующим HTTP-запросом (в параметре запроса указывается имя вызываемого действия: wikiname/Page?action=ActionName). Результат, возвращаемый действием, возвращается как результат HTTP-запроса

    • Парсеры (parsers) предназначены для обработки самостоятельных текстов на различных языках (например, рендеринг HTML, рендеринг графов, описанных на языке dot, и так далее)
  • В случае необходимости расширения функциональности необходимо учитывать следующее:
    • Расширения wiki-синтаксиса реализуются в виде макросов (например, http://uneex.ru/eSyr/WikiHack/Macros/PassportLink)

    • При расширении функциональности помимо написания собственно действия необходимо предоставить пользовательский интерфейс к нему. Обычно это выполняется в виде соответствующего макроса (например, макрос http://uneex.ru/eSyr/WikiHack/Macros/MaterialFiles для использования соответствующего действия http://uneex.ru/eSyr/WikiHack/Actions/MaterialFiles) или изменения темы wiki.

Организация процесса обработки фрагментов лекций

  • В процессе выполнения того или иного вида работ необходимо отслеживать её статус.
  • Отслеживать состояние больших кусков работ (например, состояние курса) на основании состояния маленьких.
  • Эти возможности были реализованы в рамках макроса ExtractModules, который агрегировал таблицы специального вида с указанного списка страниц и рассчитывал по ним статистику (сколько сделано и когда это закончится)

    • Требование к организации процесса — поддерживать формат таблички и своевременно её обновлять (это прописано в полиси, см., например, http://uneex.ru/PSPO/Policy/Lections)

Хранение иерархии файлов, связанной с определённой страницей

  • В процессе работы с материалами необходимо было хранить для каждого материала дерево файлов, в него входящих. На данный момент MoinMoin не предоставляет такой возможности.

  • Необходимая функциональность была реализована в виде действия MaterialFiles (http://uneex.ru/eSyr/WikiHack/Actions/MaterialFiles) и одноимённого макроса, предоставлявшего к нему пользовательский интерфейс (http://uneex.ru/eSyr/WikiHack/Macros/MaterialFiles)

  • Пример использования можно пронаблюдать на любой странице паспорта материала (http://uneex.ru/PspoMaterials)

  • Требование к организации процесса — при необходимости использования функциональности действия необходимо разместить макрос в тексте страницы
  • Возможно, более правильным с архитектурной точки зрения было бы реализовывать необходимую функциональность путём модификации имеюшегося макроса AttachFile, но на момент разработки это было признано нецелесообразным

Полезные мелочи

  • Для удобства формирования паспорта были созданы пара макрос/действие (http://uneex.ru/eSyr/WikiHack/Macros/CreateMaterialPassport / http://uneex.ru/eSyr/WikiHack/Actions/CreateMaterialPassport), которые позволяли его создавать путём заполнения формы, в результате чего на основании имеющегося шаблона генерировалась страница паспорта. Пример макроса можно пронаблюдать на странице со списком материалов (http://uneex.ru/PspoMaterials)

  • Для удобства формирования информации о формате и лицензии были написаны небольшие макросы (http://uneex.ru/eSyr/WikiHack/Macros/FormatInfo, http://uneex.ru/eSyr/WikiHack/Macros/LicenseInfo), которые вставляли текст описания того или иного формата/лицензии по его названию. Описания брались с соответствующих страниц.

  • Для удобочитаемости ссылок на материалы был написан макрос PassportLink (http://uneex.ru/eSyr/WikiHack/Macros/PassportLink), который использовал информацию со страницы паспорта (название, формат) для формирования текста ссылки (и иконки для неё)

Результат: продукт

Структура получившегося корпуса материалов:

  • Материал = Паспорт + Файлы; внутренний и внешние материалы
  • Модуль = Лекционный Минимум * Материалы + Комментарии
  • Курс = сумма Модулей
  • Побочный объект: Книга = самодостаточная сумма Материалов (http://uneex.ru/Books , «Пользовательские и технические аспекты ПСПО (цикл лекций)»)

Результат: технология

  • Использование Wiki MoinMoin

  • Доработка MoinMoin

  • Дисциплина работы: инварианты во внутренних материалах, правила импорта внешних и т. п.

Приятная неожиданность: отчуждаемость контента, в т. ч. в виде автономного www-сервера на CD (реализовано в виде небольшого скрипта на shell, http://uneex.ru/UneexStandalone).

Задние мысли

  • От каждого — по способностям:
    • Только один род задач на каждого исполнителя
    • Разумная нагрузка
  • Высокая роль внутренней мотивации
  • Необходимость автоматического разделения "готовой" и "разрабатываемой" частей при отчуждении
  • Необходимость отслеживать устаревание

Можно ли таким способом написать книгу? Сделать многокомпонентную документацию?

FrBrGeorge/Chelyabinsk2009/PspoDocumentationProcess (last edited 2009-04-13 11:50:57 by FrBrGeorge)