• Originated from FrBrGeorge/AlsoSprachZaratustra

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• За каждый фрагмент отвечает конкретный исполнитель каждого этапа (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).

Задние мысли

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

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