Differences between revisions 3 and 4
Revision 3 as of 2009-02-14 20:50:43
Size: 21590
Editor: FrBrGeorge
Comment:
Revision 4 as of 2009-02-15 02:17:58
Size: 18942
Editor: FrBrGeorge
Comment:
Deletions are marked like this. Additions are marked like this.
Line 2: Line 2:
= Командная разработки свободных учебных материалов по проекту 'Документирование ПСПО" = = Командная разработки свободных учебных материалов по проекту «Документирование ПСПО» =
Line 6: Line 6:
== Тезисный план ==
=== Постановка частной задачи ===
== Введение ==

Разработка и пилотное внедрение «Пакета Свободного Программного Обеспечения для образовательных учреждений РФ» включала в себя задачу подготовки учебных курсов для десяти категорий пользователей.

Задача «в кратчайшие сроки подготовить 10 учебных курсов по новому программному продукту силами разработчиков этого программного продукта» не выглядит разумно поставленной. Для того, чтобы её всё-таки решить, пришлось пойти на некоторые технические, организационные и методические уловки,

В результате этого решения были выработаны, как нам представляется, заслуживающие интереса методы как взаимодействия внутри команды, так и собственно формирования контента.

Текст представлен в форме тезисного плана, так как рамки доклада не позволят развернут его в полном объёме; планируется освещение только тех сторон процесса, которые вызовут наибольший интерес участников конференции.

== Постановка частной задачи ==
Line 15: Line 24:
=== Организация рабочего процесса ===
Курсы были представлены в виде наборов модулей (частей), в результате чего оказалось, что имеется ненулевое их (модулей) пересечение. В итоге, для уменьшения количества работ каждый курс был представлен как набор модулей, и дальше работа происходила уже над ними (и не подразумевала написание цельных независимых курсов).
== Организация рабочего процесса ==
Line 18: Line 26:
Рабочий процесс был разбит на следующие части:
 * Подготовка новых материалов (Also Sprach Zaratustra)
Рабочий процесс:
Line 21: Line 28:
 * Подготовка новых материалов
Line 22: Line 30:
 * Наполнение модулей
Line 24: Line 31:
Далее, организация процесса работ включала в себя следующее:
 * Формирование полиси (http://uneex.ru/PSPO/Policy)
 * Подготовка технической базы (использование wiki (MoinMoin) с дополнительным программированием и установленной дисциплиной работы.)
Организация:
 * Формирование дисциплины совместной работы (http://uneex.ru/PSPO/Policy)
 * Подготовка технической базы (Wiki-платформы MoinMoin с дополнительным программированием и установленной дисциплиной работы.)
Line 30: Line 37:
==== Подготовка новых материалов (Also Sprach Zaratustra) ====
  1.#0 «Лекции» (16 ак. ч. в неделю)
  1. Конспектирование online
=== Наполнение курсов материалами (подготовка модулей) ===
Модуль:
   * '''лекционный минимум''' — развёрнутый тематический план части курса
   * '''итоговый текст''' — лекционный минимум, дополненный ''обязательными'' ссылками на материалы, и, при необходимости, комментариями.
Организация (http://uneex.ru/PSPO/Policy/Modules):
  1. Архитектор составляет «Лекционный минимум»
    * Персональная ответственность
    * Критерий выбора исполнителя: знакомство с темой модуля
  1. Исполнитель из команды подбирает ссылки на материалы, содержащие информацию по каждой теме
    * Критерий качества: покрытие материалами всего лекционного минимума, желательно, из разнородных источников
    * Все использованные внешние материалы импортируются (см. далее)

=== Подготовка имеющихся материалов ===
'''Материал''': любой документ, содержащий информацию в рамках курсов
  * Многообразие форматов:
    * Текст в wiki-разметке (обрабатывается wiki-платформой), просматриваемый в браузере
    * HTML-дерево, которое также просматривается в браузере
    * Файлы различных форматов (например, PDF), просматриваемые сторонними программами
  * Отчуждаемость материала:
    * Обязательный импорт сторонних материалов в общий корпус (http://uneex.ru/PspoMaterials)
    * Паспорт материала:
      * Название, авторство и источник
      * Формат материала (wiki, HTML, ODT, PDF, ...) (http://uneex.ru/PspoMaterials/FormatInfo)
      * Лицензия, под которой распространяется материал. В рамках проекта использовались материалы только под свободными лицензиями. (http://uneex.ru/PspoMaterials/LicenseInfo)
     * Аннотация (если есть)
Материалы добавляют (и оформляют паспорт) ответственные за работу над модулем в случае необходимости (на последнем этапе для наполнения модулей в основном использовались уже имеющиеся материалы, так как накопленный их корпус покрывал курсы чуть менее, чем полностью).

=== Подготовка новых материалов (Also Sprach Zaratustra) ===
  1.#0 '''Лекции''' (16 ак. ч. в неделю)
  1. '''Конспектирование''' online, а также создание иллюстративного материала
Line 34: Line 68:
    1. Генерирование демонстрационных материалов (скриншоты, скрипты, логи). В последствии эти материалы интегрировались в текст фрагмента на этапе расшифровки
  1. «Расшифровка»: воссоздание структуры лекции
  1. '''Расшифровка''': воссоздание структуры лекции
Line 38: Line 71:
  1. «Перевод на русский»   1. '''Перевод на русский'''
Line 40: Line 73:
  1. «Научное редактирование»   1. '''Научное редактирование'''
Line 42: Line 75:
Организация:
  * Принцип «один человек — одна задача» (http://uneex.ru/PspoTasks)
  * Принцип персональной ответственности (http://uneex.ru/PspoClasses/Status)
  * Содержательное редактирование сведено к минимуму (иногда с небольшой потерей качества)
  * Перераспределение «затянутых» работ
Line 43: Line 81:
 * За каждый фрагмент отвечает конкретный исполнитель каждого этапа (http://uneex.ru/PspoClasses/Status).
 * Каждый из участников имел свою специализацию в силу собственных качеств и занимался только определённым видом работ (http://uneex.ru/PspoTasks).
== Использование MoinMoin ==
MoinMoin:
  * Современная Wiki-платформа
  * Имеет минимальные требования по установке
  * Написана на Python, легко расширяется и модифицируется
Проделанные модификации:
  * Простейшие средства ''планирования и мониторинга'' рабочего процесса
  * Хранение ''иерархии файлов'', связанной с определённой страницей
  * Автоматическое создание и оформление ссылок на объекты
Line 46: Line 91:
Содержательное редактирование сведено к минимуму (иногда с небольшой потерей качества), организаторская работа и т .п.
 * Содержательное редактирование проводилось того, когда было решено, что тот или иной фрагмент лекции стоит дополнить или изменить (достаточно редкая ситуация, обычно — оба раза — возникавшая из-за недостатка времени на демонстрацию примеров)
 * Организация процесса сводилась к своевременному размещению материалов и назначению ответственных согласно их текущей загруженности (как внутри проекта, так и вне его), а также к отслеживанию задержек по выполнению тех или иных этапов работ (эта работа в последствии была частично автоматизирована, 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 ===
Line 93: Line 102:
==== Организация процесса обработки фрагментов лекций ==== === Организация процесса обработки фрагментов лекций ===
Line 99: Line 108:
==== Хранение иерархии файлов, связанной с определённой страницей ==== === Хранение иерархии файлов, связанной с определённой страницей ===
Line 106: Line 115:
==== Полезные мелочи ==== === Полезные мелочи ===
Line 113: Line 122:
  * Материал = Паспорт + Файлы; внутренний и внешние материалы
  * Модуль = Лекционный Минимум * Материалы + Комментарии
  * Курс = сумма Модулей
  * Побочный объект: Книга = самодостаточная сумма Материалов (http://uneex.ru/Books , «Пользовательские и технические аспекты ПСПО (цикл лекций)»)
  * '''Материал''' = Паспорт + Файлы; внутренний и внешние материалы
  * '''Модуль''' = Лекционный Минимум * Материалы + Комментарии
  * '''Курс''' = сумма Модулей + методические рекомендации
  * Побочный объект: '''Книга''' = самодостаточная сумма Материалов (http://uneex.ru/Books , «Пользовательские и технические аспекты ПСПО (цикл лекций)»)

Командная разработки свободных учебных материалов по проекту «Документирование ПСПО»

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

Введение

Разработка и пилотное внедрение «Пакета Свободного Программного Обеспечения для образовательных учреждений РФ» включала в себя задачу подготовки учебных курсов для десяти категорий пользователей.

Задача «в кратчайшие сроки подготовить 10 учебных курсов по новому программному продукту силами разработчиков этого программного продукта» не выглядит разумно поставленной. Для того, чтобы её всё-таки решить, пришлось пойти на некоторые технические, организационные и методические уловки,

В результате этого решения были выработаны, как нам представляется, заслуживающие интереса методы как взаимодействия внутри команды, так и собственно формирования контента.

Текст представлен в форме тезисного плана, так как рамки доклада не позволят развернут его в полном объёме; планируется освещение только тех сторон процесса, которые вызовут наибольший интерес участников конференции.

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

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

Допущения:

  1. Модульная структура курсов
  2. Отказ от покрытия «чистыми» лекционными материалами

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

Рабочий процесс:

  • Подготовка модулей
  • Подготовка новых материалов
  • Подготовка имеющихся материалов

Организация:

  • Формирование дисциплины совместной работы (http://uneex.ru/PSPO/Policy)

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

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

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

Модуль:

  • лекционный минимум — развёрнутый тематический план части курса

  • итоговый текст — лекционный минимум, дополненный обязательными ссылками на материалы, и, при необходимости, комментариями.

Организация (http://uneex.ru/PSPO/Policy/Modules):

  1. Архитектор составляет «Лекционный минимум»
    • Персональная ответственность
    • Критерий выбора исполнителя: знакомство с темой модуля
  2. Исполнитель из команды подбирает ссылки на материалы, содержащие информацию по каждой теме
    • Критерий качества: покрытие материалами всего лекционного минимума, желательно, из разнородных источников
    • Все использованные внешние материалы импортируются (см. далее)

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

Материал: любой документ, содержащий информацию в рамках курсов

  • Многообразие форматов:
    • Текст в wiki-разметке (обрабатывается wiki-платформой), просматриваемый в браузере
    • HTML-дерево, которое также просматривается в браузере
    • Файлы различных форматов (например, PDF), просматриваемые сторонними программами
  • Отчуждаемость материала:
    • Обязательный импорт сторонних материалов в общий корпус (http://uneex.ru/PspoMaterials)

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

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

      • Аннотация (если есть)

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

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

  1. Лекции (16 ак. ч. в неделю)

  2. Конспектирование online, а также создание иллюстративного материала

    • критерий качества: не упускать ключевых моментов лекции
  3. Расшифровка: воссоздание структуры лекции

    • условие: расшифровщик присутствует на лекции
    • критерий качества: «переводчику» должно быть понятно, даже если он не был на лекции
  4. Перевод на русский

    • критерий качества: не потерять в процессе литредактуры значимых утверждений и формулировок
  5. Научное редактирование

    • критерий качества: связность конечного текста

Организация:

  • Принцип «один человек — одна задача» (http://uneex.ru/PspoTasks)

  • Принцип персональной ответственности (http://uneex.ru/PspoClasses/Status)

  • Содержательное редактирование сведено к минимуму (иногда с небольшой потерей качества)
  • Перераспределение «затянутых» работ

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

MoinMoin:

  • Современная Wiki-платформа
  • Имеет минимальные требования по установке
  • Написана на 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)