CIFS: curious information funneled sometimes

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 или других документационных местах.