Differences between revisions 4 and 5
Revision 4 as of 2009-02-15 02:17:58
Size: 18942
Editor: FrBrGeorge
Comment:
Revision 5 as of 2009-02-15 03:26:29
Size: 15341
Editor: FrBrGeorge
Comment:
Deletions are marked like this. Additions are marked like this.
Line 92: Line 92:
 * В 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.
  * Новые синтаксические конструкции — ''Macros''
  * Новые способы обработки контента — ''Actions'' (действие указывается в URL)
  * Новые форматы входного текста (например, другие Wiki, CSV, DOT, HTML) — ''Parsers''
  * Новые форматы вывода (не только HTML, а, например, PDF, !DocBook, ODT) — ''Formatters''
  * Новое оформление — ''Themes''
  * Любое расширение — обычный модуль Python, имеющий простой и прозрачный доступ ко внутренним API MoinMoin (рекомендуется изучить в первую очередь возможности модуля `MoinMoin.util`)
Новое ''действие'' (action) обычно сопровождается новым ''макросом'' (macro), создающим ссылку, содержащую действие, или исправлением ''оформления'' (theme)
Line 102: Line 100:
=== Организация процесса обработки фрагментов лекций ===
 * В процессе выполнения того или иного вида работ необходимо отслеживать её статус.
 * Отслеживать состояние больших кусков работ (например, состояние курса) на основании состояния маленьких.
 * Эти возможности были реализованы в рамках макроса !ExtractModules, который агрегировал таблицы специального вида с указанного списка страниц и рассчитывал по ним статистику (сколько сделано и когда это закончится)
  * Требование к организации процесса — поддерживать формат таблички и своевременно её обновлять (это прописано в полиси, см., например, http://uneex.ru/PSPO/Policy/Lections)
=== Планирование и мониторинг рабочего процесса (макро ExtractModules) ===
Свойства модуля:
  * Зависимость по тематике от других модулей (т. н. «Необходимые знания»)
  * Готовность (уровень и сроки, сообразно рабочему процессу)
Задача: вычислить готовность всего курса и список требований к знаниям слушателей
Решение (http://uneex.ru/PSPO/Policy/Lections):
  * Каждый модуль содержит таблицу, отмечающую готовность и зависимости (обновляется исполнителем)
  * Курс формируется из списка модулей автоматически
Line 109: Line 110:
 * В процессе работы с материалами необходимо было хранить для каждого материала дерево файлов, в него входящих. На данный момент MoinMoin не предоставляет такой возможности.
 * Необходимая функциональность была реализована в виде действия !MaterialFiles (http://uneex.ru/eSyr/WikiHack/Actions/MaterialFiles) и одноимённого макроса, предоставлявшего к нему пользовательский интерфейс (http://uneex.ru/eSyr/WikiHack/Macros/MaterialFiles)
 * Пример использования можно пронаблюдать на любой странице паспорта материала (http://uneex.ru/PspoMaterials)
 * Требование к организации процесса — при необходимости использования функциональности действия необходимо разместить макрос в тексте страницы
 * Возможно, более правильным с архитектурной точки зрения было бы реализовывать необходимую функциональность путём модификации имеюшегося макроса !AttachFile, но на момент разработки это было признано нецелесообразным
Задача: работа с ''материалами'', представленными в виде дерева файлов и каталогов (например, полными HTML-страницами)
Решение: пара ''действие+макро'' (http://uneex.ru/eSyr/WikiHack/Actions/MaterialFiles и http://uneex.ru/eSyr/WikiHack/Macros/MaterialFiles), в которой использование макро !MaterialFiles в тексте страницы раскрывается в изображение дерева файлов. Соответствующие манипуляции файлами — обращение к действию !MaterialFiles и его вариациям.

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

Возможно, более правильным было бы модифицировать имеющийся макрос !AttachFile, но на момент разработки это было признано нецелесообразным
Line 120: Line 122:
=== Результат: продукт === == Результат ==
Line 127: Line 129:
=== Результат: технология ===
 * Использование Wiki MoinMoin
 * Доработка MoinMoin
 * Дисциплина работы: инварианты во внутренних материалах, правила импорта внешних и т. п.
Приятная неожиданность: отчуждаемость контента, в т. ч. в виде автономного www-сервера на CD (реализовано в виде небольшого скрипта на shell, http://uneex.ru/UneexStandalone).

=== Задние мысли ===
  * От каждого — по способностям:
    * Только один род задач на каждого исполнителя
    * Разумная нагрузка
=== Замечания и предложения ===
Line 140: Line 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 (last edited 2009-04-13 11:50:57 by FrBrGeorge)