abbra: (Default)
[personal profile] abbra
[livejournal.com profile] 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 или других документационных местах.
This account has disabled anonymous posting.
If you don't have an account you can create one now.
No Subject Icon Selected
More info about formatting

If you are unable to use this captcha for any reason, please contact us by email at support@dreamwidth.org

April 2016

S M T W T F S
     12
3456789
1011121314 1516
17181920212223
24252627282930

Most Popular Tags

Style Credit

Expand Cut Tags

No cut tags
Page generated Jul. 26th, 2025 09:41 pm
Powered by Dreamwidth Studios