%\documentclass{article} % %\usepackage[utf8]{inputenc} %\usepackage[normalem]{ulem} %\usepackage[english,russian]{babel} %\usepackage[unicode]{hyperref} %\usepackage{calc} %\usepackage{graphicx} %\usepackage{indentfirst} %\usepackage{url} %\DeclareGraphicsExtensions{.svg,.eps} % %\begin{document} % \author{Сыромятников Е. Л., Курячий Г. В.} \city{Москва} \affiliatio{ООО ALT Linux} \projecttitle{семинар UNИX} \projecturl{\url{http://uneex.ru/}} \title{Использование wiki-сервера MoinMoin для совместной разработки документации} \maketitle \begin{abstract} В докладе освещается проблема совместной разработки документации, рассматривается возможность использования wiki-технологий для решения задач, возникающих в рамках данной проблемы и предлагается решение на базе модифицированного wiki-сервера MoinMoin, позволяющее организовать процесс совместной разработки документации. \end{abstract} \section{Предпосылки} Летом 2008 года блы начат проект по документированию ПСПО \cite{Kouryachy}, \cite{Kouryachy+Syromyatnikov}. В его рамках требовалось создание комплекта документации, удовлетворяющего ряду требований. К особенностям проекта можно причислить жёсткие временные рамки, возникшие по различным причинам. В результате анализа требований было решено использовать для совместной разработки wiki-движок MoinMoin с необходимыми модификациями. Далее рассматривается полученный набор модификаций. \section{Постановка задачи} Рассмотрим условия и допущения, в рамках которых мы рассматриваем задачу совместной разработки документации: \begin{itemize} \item[--] Документация представляет собой набор документов, связанных гипертекстовыми ссылками. \item[--] Структура документации может быть заранее не определена. \item[--] Документация организована в виде курсов, состоящих из модулей. Данный подход позволяет разрабатывать отдельные части документации независимо. \item[--] Форматы материалов, используемых в документации, не ограничиваются, при этом процесс работы с ними должен быть по возможности унифицирован. \item[--] Процесс разработки централизован. Анализ случая использования децентрализованных средств разработки выходит за рамки данной работы. \item[--] Мобильность опубликованной версии. ПО, позволяющее просматривать опубликованную документацию, должно быть переносимым — не иметь или иметь минимальное количество системных зависимостей. \end{itemize} \section{wiki и MoinMoin} Выбор wiki в качестве технологии совместной разработки был сделан по следующим причинам: \begin{itemize} \item[--] Wiki изначально ориентирована на совместную работу, и её реализации предусматривают соответствующие инструменты (контроль версий, прав доступа, механизм разрешения конфликтов) \item[--] Простота: документ в wiki-разметке представляет из себя текстовый файл \item[--] Гибкость: набор wiki-документов не имеет предопределённой жёстко заданной структуры \end{itemize} Выбор MoinMoin в качестве основы был обусловлен рядом факторов: \begin{itemize} \item[--] Современная wiki-платформа, активные сообщество и поддержка \item[--] Написан на Python, легко расширяется и модифицируется \item[--] Имеет минимальные требования по установке в плане программных зависимостей (на сервере требуется только наличие интерпретатора Python) \end{itemize} \section{Реализация} Рассмотрим подробнее возможности, предлагаемые MoinMoin, которые можно использовать для организации соместной разработки документации. \begin{itemize} \item[--] Механизм парсеров и форматирования с использованием промежуточного формата на основе wikiDOM \cite{wikiDOM} позволяет иметь большое количество входных и выходных форматов. В рамках проекта документирования ПСПО на основе этих механизмов был реализован экспорт в HTML-tree, впоследствии был добавлен частичный экспорт в формат Moodle course backup \item[--] Использование фильтров-обработчиков, извлекающих текстовую информацию из файлов различных форматов позволяет генерировать поисковый индекс и использовать его. \item[--] Механизмы расширения функциональности MoinMoin (actions, macros) позволяют добавить возможности, необходимые для решения задачи, которые изначально отсутствовали в MoinMoin. \end{itemize} \section{Возможности} Для единого способа обработки разнородных внешних материалов была выделена часть с метаинформацией (т. н. \emph{паспорт}), в котором содержатся данные об авторе, источнике, лицензии, формате, а также краткая аннотация. Содержательная часть материала сохраняется либо в wiki, либо в статическом хранилище и, по возможности (в зависимости от наличия фильтра для данного формата), индексируется. Для работы с материалами добавлена возможность создания ссылок на них (на паспорта или на собственно файлы). \begin{figure}[h] \includegraphics[height = 158.40pt, width = 505.69pt]{course-module-material} \caption{Организация документации. Курсы представляют из себя коллекции модулей. Модули содержат ссылки на материалы.} \end{figure} Для поддержки модульности были написаны макросы, обрабатывавшие таблицы специального вида на страницах модулей и в соответствии с информацией, указанной в них Организация работы Поддержка работы с курсами и модулями Публикация. Здесь можно выделить следующие аспекты: \begin{itemize} \item[--] Создание автономного комплекта документации \item[--] Публикация части документации, замкнутой по зависимостям \end{itemize} Первая задача решалась путём модификации wiki-сервера MoinMoin (это требовалось в связи с тем, что он не был расчитан на работу с носителем, к которому нет доступа на запись). Вторая задача решалась построением графа зависимостей и выделения небоходимого подграфа. \section{Результаты} Создан набор дополнений и модификаций wiki-сервера MoinMoin, успешно использовавшийся в рамках проекта документирования ПСПО \cite{Kouryachy+Syromyatnikov}. Данные модификации опубликованы на сайте проекта \cite{UneexDisc} и распространяются под GPL. \section{Вместо заключения} Серебряной пули нет \cite{brooks}. Данное решение не позволяет делать документацию из чего попало в произвольном выходном формате. Оно лишь может помочь организовать процесс сбора и категоризации имеющихся материалов, таким образом, чтобы ими было чуть удобнее пользоваться. \begin{thebibliography}{9} \bibitem{Kouryachy} \textit{Курячий Г. В.} Проблемы и методы командной разработки свободных, учебных материалов, \emph{«Четвёртая конференция «Свободное программное обеспечение в высшей школе» (Переславль). Тезисы докладов.»}, 2009, стр. 60—63, \url{http://www.altlinux.ru/media/book-thesis-Pereslavl-2009-4.pdf}. \bibitem{Kouryachy+Syromyatnikov} \textit{Курячий Г. В., Сыромятников Е. Л.} Командная разработка свободных учебных материалов по проекту «Документирование пакета свободного программного обеспечения», \emph{«Свободное программное беспечение в образовании. Сборник трудов Всероссийской конференции (г. Челябинск)»}, под редакцией А. В. Панюкова, Издательство ЮУрГУ, 2009, стр. 14—18, \url{http://freeschool.altlinux.ru/wp-content/uploads/2009/03/chelyabinsk_25-26_march_2009.pdf}. \bibitem{wikiDOM} \url{http://moinmo.in/MoinDev/WikiDom} \bibitem{UneexDisc} \url{http://disc.uneex.ru/} \bibitem{brooks} \textit{Брукс Ф.} Мифический человеко-месяц, или как создаются программные системы. \url{http://www.lib.ru/CTOTOR/BRUKS/mithsoftware.txt} \end{thebibliography} % %\end{document}