Различия между версиями 1 и 5 (по 4 версиям)
Версия 1 от 2009-02-14 18:20:32
Размер: 13776
Редактор: eSyr
Комментарий:
Версия 5 от 2009-02-15 03:26:29
Размер: 15341
Редактор: FrBrGeorge
Комментарий:
Удаления помечены так. Добавления помечены так.
Строка 1: Строка 1:
 ''Originated from [[FrBrGeorge/AlsoSprachZaratustra]]''

= Проблемы и методы командной разработки свободных учебных материалов =
Ключевые слова: ПСПО, СПО, документация, командная разработка, учебный материал, wiki
## unicodize
= Командная разработки свободных учебных материалов по проекту «Документирование ПСПО» =
Строка 8: Строка 6:
== Тезисный план ==
=== Постановка частной задачи ===
== Введение ==

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

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

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

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

== Постановка частной задачи ==
Строка 13: Строка 20:
Допущения:
 1. Модульная структура курсов
 1. Отказ от покрытия «чистыми» лекционными материалами
Строка 14: Строка 24:
=== Организация рабочего процесса ===
Курсы были представлены в виде наборов модулей (частей), в результате чего оказалось, что имеется ненулевое их (модулей) пересечение. В итоге, для уменьшения количества работ кажды курс был представлен как набор модулей, и дальше работа происходила уже над ними (и не подразумевала написание цельных независимых курсов).
== Организация рабочего процесса ==
Строка 17: Строка 26:
Рабочий процесс был разбит на следуюшие части:
 * Подготовка новых материалов (Also Sprach Zaratustra)
Рабочий процесс:
Строка 20: Строка 28:
 * Подготовка новых материалов
Строка 21: Строка 30:
 * Наполнение модулей
Строка 23: Строка 31:
Далее, организация процесса работ включала в себя следующее:
 * Формирование полиси (http://uneex.ru/PSPO/Policy)
 * Подготовка технической базы (использование wiki (MoinMoin) с дополнительным программированием и установленной дисциплиной работы.)
Организация:
 * Формирование дисциплины совместной работы (http://uneex.ru/PSPO/Policy)
 * Подготовка технической базы (Wiki-платформы MoinMoin с дополнительным программированием и установленной дисциплиной работы.)
Строка 29: Строка 37:
==== Подготовка новых материалов (Also Sprach Zaratustra) ====
  1.#0 "Лекции" (16 ак. ч. в неделю)
  1. Конспектирование online
    * критерий качества: не упускать ключевых моментов лекции
    1. Генерирование демонстрационных материалов (скриншоты, скрипты, логи). В последствии эти материалы интегрировались в текст фрагмента на этапе расшифровки
  1. "Расшифровка": воссоздание структуры лекции
    * условие: расшифровщик присутствует на лекции
    * критерий качества: "переводчику" должно быть понятно, даже если он не был на лекции
  1. "Перевод на русский"
    * критерий качества: не потерять в процессе литредактуры значимых утверждений и формулировок
  1. "Научное редактирование"
    * критерий качества: связность конечного текста

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

Содержательное редактирование сведено к минимуму (иногда с небольшой потерей качества), организаторская работа и т .п.
 * Содержательное редактирование проводилось того, когда было решено, что тот или иной фрагмент лекции стоит дополнить или изменить (достаточно редкая ситуаця, обычно — оба раза — возникавшая из-за недостатка времени на демострацию примеров)
 * Организация процесса сводилась к своевремменому размещению материалов и назначению ответственных согластно их текущей загруженности (как внутри проекта, так и вне его), а также к отслеживанию задержек по выполнению тех или иных этапов работ (эта работа в последствии была частично автоматизирована, http://uneex.ru/PspoClasses/Status?action=AttachFile&do=view&target=status.sh)
Строка 50: Строка 38:
 * Каждый модуль состоит из ''лекционного минимума'' -- развёрнутого тематического плана будущего фрагмента курса (модуля) и ''итогового текста'', представляющего из себя лекционный минимум, дополненный ссылками на материалы, и, при необходимости, комментариями.
 * Архитектор составляет "Лекционный минимум"
 * За каждый модуль отвечает конкретный исполнитель
  * Критерий выбора исполнителя: тема, освещаемая в модуле, ему отностильено близка
 * Исполнитель из команды подбирает ссылки на материалы, содержащие информацию по каждой теме
  * Критерий качества: покрытие материалами всего лекционного минимума, желательно, из разнородных источников (например, лекции и документация ALT Linux) (http://uneex.ru/PSPO/Policy/Modules)
 * Все использованные внешние материалы импортируются (см. далее)
Модуль:
   * '''лекционный минимум''' — развёрнутый тематический план части курса
   * '''итоговый текст''' — лекционный минимум, дополненный ''обязательными'' ссылками на материалы, и, при необходимости, комментариями.
Организация (http://uneex.ru/PSPO/Policy/Modules):
  1. Архитектор составляет «Лекционный минимум»
    * Персональная ответственность
    * Критерий выбора исполнителя: знакомство с темой модуля
  1. Исполнитель из команды подбирает ссылки на материалы, содержащие информацию по каждой теме
    * Критерий качества: покрытие материалами всего лекционного минимума, желательно, из разнородных источников
    * Все использованные внешние материалы импортируются (см. далее)
Строка 59: Строка 50:
 * Материал, некий документ, несущий некую информацию в рамках курсов
 * Материалы могут быть из различных источников и иметь различный формат. Т. о., материалом являются, например, описанные выше лекции. Также, среди материалов присутствуют нектороая часть документации ALT Linux, книги, howto, rfc, иллюстрация, статья в википедии и прочее. Среди основных видов материалов можно выделить
:   * Текст в wiki-разметке (обрабатываемый собственно wiki-движком), просматриваемый в браузере
  * HTML-дерево, которое также просматривается в браузере
  * Файлы различных форматов, просматриваемые сторонними программами, внешними по отношение к браузеру
* В виду необходимости отчуждаемости итоговой работы все материалы должны быть проимпортированы (положены в рабочее дерево материалов) и снабжены идентификационной и описательной информацией — паспортом (список всех материалов: http://uneex.ru/PspoMaterials). В паспорт включаются следующие аспекты материала:
  * Его название, авторство и источник
* Формат материала (wiki, HTML, ODT, PDF, ...) (http://uneex.ru/PspoMaterials/FormatInfo)
  * Лицензия, под которой распространяется материал. В рамках проекта использовались материалы только под свободными лицензиями. (http://uneex.ru/PspoMaterials/LicenseInfo)
  * Аннотация (если есть)
 * Материалы добавляют (и оформлояют паспорт) ответственные за работу над модулем в случае необходимости (на последнем этапе для наполнения модулей в основном использовались уже имеющиеся материалы, так как накопленный их корпус покрывал курсы чуть менее, чем полностью)
'''Материал''': любой документ, содержащий информацию в рамках курсов
 
* Многообразие форматов:
  
* Текст в wiki-разметке (обрабатывается wiki-платформой), просматриваемый в браузере
   * HTML-дерево, которое также просматривается в браузере
    * Файлы различных форматов (например, PDF), просматриваемые сторонними программами
 
* Отчуждаемость материала:
    * Обязательный импорт сторонни
х материалов в общий корпус (http://uneex.ru/PspoMaterials)
    * Паспорт материала:
      * Название, авторство и исто
чник
    
* Формат материала (wiki, HTML, ODT, PDF, ...) (http://uneex.ru/PspoMaterials/FormatInfo)
     * Лицензия, под которой распространяется материал. В рамках проекта использовались материалы только под свободными лицензиями. (http://uneex.ru/PspoMaterials/LicenseInfo)
     * Аннотация (если есть)
Материалы добавляют (и оформляют паспорт) ответственные за работу над модулем в случае необходимости (на последнем этапе для наполнения модулей в основном использовались уже имеющиеся материалы, так как накопленный их корпус покрывал курсы чуть менее, чем полностью).
Строка 71: Строка 64:
=== Наполнение модулей ===
 * Ответственный, назначенный исполниетелем по данному модулю, подбирает набор материалов, покрывающих лекционный минимум, после чего формирует итоговый текст, используя собранные материалы, и, при необходимости, комментируя их (см., например, http://uneex.ru/PspoModules/FreeLicense — в виду специфики предмета потребовались обширные комментарии. Другой пример: http://uneex.ru/PspoModules/MigrationUser — содержание модуля компактно покрыто материалами лекций)
=== Подготовка новых материалов (Also Sprach Zaratustra) ===
  1.#0 '''Лекции''' (16 ак. ч. в неделю)
  1. '''Конспектирование''' online, а также создание иллюстративного материала
    * критерий качества: не упускать ключевых моментов лекции
  1. '''Расшифровка''': воссоздание структуры лекции
    * условие: расшифровщик присутствует на лекции
    * критерий качества: «переводчику» должно быть понятно, даже если он не был на лекции
  1. '''Перевод на русский'''
    * критерий качества: не потерять в процессе литредактуры значимых утверждений и формулировок
  1. '''Научное редактирование'''
    * критерий качества: связность конечного текста
Организация:
  * Принцип «один человек — одна задача» (http://uneex.ru/PspoTasks)
  * Принцип персональной ответственности (http://uneex.ru/PspoClasses/Status)
  * Содержательное редактирование сведено к минимуму (иногда с небольшой потерей качества)
  * Перераспределение «затянутых» работ
Строка 74: Строка 81:
=== Использование MoinMoin ===
 * В качестве технологической базы для совместной подготовки использовался wiki-движок MoinMoin, написанный на языке Python
 * Для поддержки различных организационных аспектов в ряде случаев потребовалось незначительное расширение его функциональности.
  * Организация процесса обработки фрагментов лекций
  * Хранение иерархии файлов, связанной с определённой страницей
  * Создание ссылок на сущности различного вида, и формирование текста ссылки в зависимости от содержимого сущности
== Использование MoinMoin ==
MoinMoin:
  * Современная Wiki-платформа
  * Имеет минимальные требования по установке
  * Написана на Python, легко расширяется и модифицируется
Проделанные модификации:
  * Простейшие средства ''планирования и мониторинга'' рабочего процесса
  * Хранение ''иерархии файлов'', связанной с определённой страницей
  * Автоматическое создание и оформление ссылок на объекты
Строка 81: Строка 91:
=== Как расширять функциональность MoinMoin ===
  * Новые синтаксические конструкции — ''Macros''
  * Новые способы обработки контента — ''Actions'' (действие указывается в URL)
  * Новые форматы входного текста (например, другие Wiki, CSV, DOT, HTML) — ''Parsers''
  * Новые форматы вывода (не только HTML, а, например, PDF, !DocBook, ODT) — ''Formatters''
  * Новое оформление — ''Themes''
  * Любое расширение — обычный модуль Python, имеющий простой и прозрачный доступ ко внутренним API MoinMoin (рекомендуется изучить в первую очередь возможности модуля `MoinMoin.util`)
Новое ''действие'' (action) обычно сопровождается новым ''макросом'' (macro), создающим ссылку, содержащую действие, или исправлением ''оформления'' (theme)
Строка 82: Строка 100:
=== Планирование и мониторинг рабочего процесса (макро ExtractModules) ===
Свойства модуля:
  * Зависимость по тематике от других модулей (т. н. «Необходимые знания»)
  * Готовность (уровень и сроки, сообразно рабочему процессу)
Задача: вычислить готовность всего курса и список требований к знаниям слушателей
Решение (http://uneex.ru/PSPO/Policy/Lections):
  * Каждый модуль содержит таблицу, отмечающую готовность и зависимости (обновляется исполнителем)
  * Курс формируется из списка модулей автоматически
Строка 83: Строка 109:
=== Результат: продукт === === Хранение иерархии файлов, связанной с определённой страницей ===
Задача: работа с ''материалами'', представленными в виде дерева файлов и каталогов (например, полными HTML-страницами)
Решение: пара ''действие+макро'' (http://uneex.ru/eSyr/WikiHack/Actions/MaterialFiles и http://uneex.ru/eSyr/WikiHack/Macros/MaterialFiles), в которой использование макро !MaterialFiles в тексте страницы раскрывается в изображение дерева файлов. Соответствующие манипуляции файлами — обращение к действию !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), который использовал информацию со страницы паспорта (название, формат) для формирования текста ссылки (и иконки для неё)

== Результат ==
Строка 85: Строка 124:
  * Материал = Паспорт + Файлы; внутренний и внешние материалы
  * Модуль = Лекционный Минимум * Материалы + Комментарии
  * Курс = сумма Модулей
  * Побочный объект: Книга = самодостаточная сумма Материалов (http://uneex.ru/Books , «Пользовательские и технические аспекты ПСПО (цикл лекций)»)
  * '''Материал''' = Паспорт + Файлы; внутренний и внешние материалы
  * '''Модуль''' = Лекционный Минимум * Материалы + Комментарии
  * '''Курс''' = сумма Модулей + методические рекомендации
  * Побочный объект: '''Книга''' = самодостаточная сумма Материалов (http://uneex.ru/Books , «Пользовательские и технические аспекты ПСПО (цикл лекций)»)
Строка 90: Строка 129:
=== Результат: технология ===
 * Использование Wiki MoinMoin
 * Доработка MoinMoin
 * Дисциплина работы: инварианты во внутренних материалах, правила импорта внешних и т. п.
Приятная неожиданность: отчуждаемость контента, в т. ч. в виде автономного www-сервера на CD.

=== Задние мысли ===
  * От каждого — по способностям:
    * Только один род задач на каждого исполнителя
    * Разумная нагрузка
=== Замечания и предложения ===
Строка 101: Строка 131:
  * Необходимость автоматического разделения "готовой" и "разрабатываемой" частей при отчуждении   * Необходимость автоматического разделения «готовой» и «разрабатываемой» частей при отчуждении
Строка 103: Строка 133:
Можно ли таким способом написать книгу? Сделать многокомпонентную документацию?

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

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

Введение

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

Задача «в кратчайшие сроки подготовить 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

  • Новые синтаксические конструкции — Macros

  • Новые способы обработки контента — Actions (действие указывается в URL)

  • Новые форматы входного текста (например, другие Wiki, CSV, DOT, HTML) — Parsers

  • Новые форматы вывода (не только HTML, а, например, PDF, DocBook, ODT) — Formatters

  • Новое оформление — Themes

  • Любое расширение — обычный модуль Python, имеющий простой и прозрачный доступ ко внутренним API MoinMoin (рекомендуется изучить в первую очередь возможности модуля MoinMoin.util)

Новое действие (action) обычно сопровождается новым макросом (macro), создающим ссылку, содержащую действие, или исправлением оформления (theme)

Планирование и мониторинг рабочего процесса (макро ExtractModules)

Свойства модуля:

  • Зависимость по тематике от других модулей (т. н. «Необходимые знания»)
  • Готовность (уровень и сроки, сообразно рабочему процессу)

Задача: вычислить готовность всего курса и список требований к знаниям слушателей Решение (http://uneex.ru/PSPO/Policy/Lections):

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

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

Задача: работа с материалами, представленными в виде дерева файлов и каталогов (например, полными HTML-страницами) Решение: пара действие+макро (http://uneex.ru/eSyr/WikiHack/Actions/MaterialFiles и http://uneex.ru/eSyr/WikiHack/Macros/MaterialFiles), в которой использование макро MaterialFiles в тексте страницы раскрывается в изображение дерева файлов. Соответствующие манипуляции файлами — обращение к действию 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 , «Пользовательские и технические аспекты ПСПО (цикл лекций)»)

Замечания и предложения

  • Высокая роль внутренней мотивации
  • Необходимость автоматического разделения «готовой» и «разрабатываемой» частей при отчуждении
  • Необходимость отслеживать устаревание

FrBrGeorge/Chelyabinsk2009/PspoDocumentationProcess (последним исправлял пользователь FrBrGeorge 2009-04-13 11:50:57)