(no subject)

[abbra]

dottedmag поднял тему релевантности документации в различных проектах состоянию проекта на конкретный момент времени. Действительно, практически везде есть проблема с утеканием документации по времени от релизов ПО. С одной стороны, в большинстве проектов используют Wiki и подобные механизмы для ведения документации, видимо, в надежде привлечь пользователей к документированию. С другой, существуют классические способы представления документации (Docbook, LaTeX, etc), которые не очень состыковываются с этой Wiki-деятельностью: проблемы совмещения и трансляции форматов для многих выступают ограничителем в интеграции подобных подходов. В результате получается, что приходится делать выбор между Wiki-подобными системами и нормальной документацией.

Однако у Wiki-подобных систем на сегодня практически нет возможности делать исторические срезы группы страниц аналогично проставлению тэгов в обычных системах версионирования, в которых ведется разработка традиционной документации. Если бы они были, то просмотр, скажем, на Wiki-движке урла /wiki/history/RELEASE_1_0/* позволял бы видеть все страницы нашей WIki, относящиеся к релизу первой версии продукта. То есть, позволял бы видеть то состояние документации, которое отражало бы выпущенный продукт.

На самом деле, это достаточно просто сделать. Для этого надо использовать Wiki с возможностью хранения документов не в "базах данных" или специально изобретенных файлах, а в нормальной распределенной системе версионирования, поддерживающей и тэги, и все остальное. Такие системы есть, по крайней мере, ikiwiki и GeekiGeeki позволяют использовать DSCM (SVN, GIT, ...). Правда, первый является wiki-компилятором, а второй напрямую не поддерживает работу с тэгами, но это небольшие проблемы. Во-первых, использование распределенной системы версионирования позволяет на самом деле не заморачиваться вопросами редактирования через веб-интерфейс (его можно сделать, ikiwiki это поддерживает, равно как и GeekiGeeki) -- возможность работы со всей Wiki локально средствами DSCM имеет вполне продуктивный смысл, а также позволяет ввести механику подписывания изменений (ключами, ответственностью и так далее). Во-вторых, при таком подходе небольшая модификация Ikiwiki для генерации содержимого по всем или выбранным тэгам видится тривиальной, так что получающийся ресурс будет доступен как в историческом плане для документирования уже выпущенных продуктов, так и в оперативном, для дальнейшего развития документации.

Педро Мела недавно писал на эту же тему. Объединив подходы Гусарова и Мелы, мы получим удобную и качественную систему в рамках ALT Linux Team: git-репозитарии для каждого в команде уже есть, осталось только кому-то одному работать над ведением "основного" репозитария, из которого силами, например, ikiwiki публикуются официальные страницы в heap.altlinux.ru или других документационных местах.

Comments

[aen-.livejournal.com]

Звучит здорово.

[duke-igthorn.livejournal.com]

А почему вики, хранящая инфу в БД, не годится для версионирования? Конечно, это не так удобно, как нативная поддержка - но периодический коммит дает "суррогатную" работу с версиями. Сценарий вполне возможный для ситуаций, когда вики уже есть и переход на новую слишком геморроен.

[abbra]

Можно, но факт в том, что неудобно. Экспортировать данные в нормальную DSCM не так уж и сложно, на самом деле.

[kiryl.livejournal.com]

SVN не является DSCM. Возможно ты имел ввиду SVK?

[abbra]

Я имел в виду в целом. Да, SVK может в данном случае служить некоторой заменой git и bzr.

[aceler.livejournal.com]

И когда мы это увидим?

В KDE сейчас в связи с новой версией творится форменный песец. Люди приходят в список рассылки и спрашивают, где в kexi кнопка поиска.

Потому что интерфейс поменялся, а документации нет, да и пока не может быть - интерфейс все еще меняется.

В общем, такая система нам бы была бы очень.

[abbra]

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

[aceler.livejournal.com]

Как только будет готов прототип, его можно будет показать хоть в KDE, хоть в gnome, хоть в любой другой проект, требующий тонны пользовательской документации.

[aceler.livejournal.com]

P.S. Желаю здравствовать!

[dottedmag.livejournal.com]

Я упирал больше на социологию - поскольку техническими средствами провалидировать корректность документации нельзя, необходим хотя бы один координатор.

[abbra]

Именно поэтому я и говорю о введении механики подписывания изменений (ключами, ответственностью и т.д.), Signed-Off и основного кадровика. Для этого как раз нужно перейти к средствам, которые такую механику поддерживают.

[romik-g.livejournal.com]

И еще принудительно заставлять тех, кто сабмиттит какой-либо код, его документировать не только с точки зрения разработчика, но и с точки зрения пользователя.

[romik-g.livejournal.com]

Как я криво выразился то.....
Но идея, надеюсь, понятна.

[netlander.livejournal.com]

Мне тоже кажется, что проблема больше организационная, чем техническая. Нужны:
1) Постоянно работающая Doc Team.
2) Одобренная и жестко выполняемая сообществом процедура выпуска релиза. Разработка документации должна быть встроена в выпуск релиза. А не существовать в параллельном мире (как это сейчас).

И это Doc Team должна стать заказчиком инструментария, с помощью будет клепаться документация. Поэтому, пока нет требований (проблем) со стороны Doc Team говорить о средствах решения практически бесполезно. Опять же с точки зрения организованности:
-- могут существовать прекрасные инструменты, но команда может не уметь ими пользоваться
-- может не существовать инструмента, но док-команда хорошо знает и может внятно объяснить core-developers что нужно сделать.
По опыту работы могу сказать, что core developers рады иногда "спуститься с небес", написать "простенькую штучку". Правда с условием, что это "очень нужно" и будет происходить _очень_ редко :-)

Re: Reply to your comment...

[dottedmag.livejournal.com]

По-хорошему, большая doc team не нужна - лучше всего код знают сами девелоперы, и им и описывать. Нужен постановщик задач и причёсыватель результата, вышедшего из-под девелоперов (в зависимости от размера проекта это можно совместить в одном человеке, либо отдать целой команде).

[abbra]

Надо сказать, что в случае ALT все члены команды через какое-то время будут использовать git, так что вопрос инструментария тут предопределен (на нижнем уровне). Почту и wiki-синтаксис практически все из них использовать умеют. Значит, дело в организационной составляющей и примитивной доработке имеющегося софта по описанному выше подходу.

Так что все возможно и достаточно быстро, при четкой концентрации внимания на задаче.