Столкнулся с необходимостью выбрать инструментарий для ведения документации по проекту. Получается, что если в команде нет отдельного (специально выделенного) человека, который ведёт всю документацию, то инструментарий должен поддерживать коллективную разработку документации. Как минимум — уметь делать versioning, diff и rollback.
Два ключевых слова — “документация” и “коллективная” приводят к очевидному решению — wiki. Решение настолько очевидно, что можно найти testimonials людей, использовавших wiki для документирования разработки software:
Во-первых, в разработке док участвовали все: манагеры, девы, кюэйцы. Каждый со своей позиции (решая профильные вопросы) и в целом.
Во-вторых, оценивать изменения состояния проекта было легко. У нас была круглосуточная разработка (головной офис в штатах) и поэтому за время сна могло многое измениться.
В-третьих, самые болезненные места было сразу видно и можно было прямо с утра озадачиться раздачей пинков в нужных направлениях. Или тут же решить самые острые вопросы (поменяв заодно тег вопроса на тег ответа). Или поставить новые проблемы в ответ на.
В-четвертых, документация была всегда у всех под рукой. Гибкая. Актуальная.
В-пятых, она активно росла. Было негласное правило: хочешь задать вопрос по теме, которая еще не описана? Впиши все, что ты помнишь, в той мере, какой считаешь нужным.
В-шестых структуру самого дерева мы регулярно реструктурировали, что позволяло нам при проектировании новых кусков логики опираться на схему уже существующих.
Очевидно, что сама по себе wiki не справляется с задачей: нужны костыли для привязки к багтрекеру, svn-у, php-docу (или его аналогу). Ещё более очевидно, нужен “архивариус” — человек, который будет поддерживать порядок в документации, реструктуризировать дерево. Похоже, что при определённой активности и дисциплинированности пользователей (т.е. разработчиков, тестеров и менеджеров) роль архивариуса удастся свести именно к поддержанию порядка.
При этом меня не покидает ощущение того, что wiki-разметка — это недо-html. А в компании, занимающейся web-разработками, основы html знает даже корпоративная морская свинка™. Спрашивается: зачем людям, знающим html, насиловать себя и писать вместо <i>привычных тегов</i> //какие-то недотеги//, которыми они нигде, кроме этой самой wiki не пользуются, в отличие от нативных html тегов?
Среди всех претензий к wiki её недо-htmlьность — самая мелкая.
А теперь самое время вернуться к тому, с чего всё это начиналось: нам нужен инструмент, позволяющий вести коллективную разработку документации. Как минимум — уметь делать versioning, diff и rollback.
А ведь у нас уже есть такой инструмент: это Control Version System, система контроля версий. Стандартная CVS позволяет делать versioning, diff и rollback для текстовых файлов.
Итак, самое дешёвое решение — вести документацию в текстовых файлах, контроль версий возложит на CVS, которая уже есть в проекте. Грубо говоря, если в CVS есть директория Source с исходниками проекта, то рядом надо сделать папку Docs с его документацией в текстовых файлах.
Беда в том, что документация — это не текст. Даже если обойтись без таблиц, иллюстраций и форматирования, документация — это как минимум гипертекст. Значит, надо вести документацию в формате html, и хранить её в CVS, ибо html файл — это текстовый файл. Редактировать документацию сможет каждый, как и в случае с wiki — для этого подойдёт любой html-редактор, даже блокнот.
Versioning для html файлов будет по-прежнему обеспечивать CVS. Единственное, что надо согласовать — это правила форматирования документации в html. Типа: для жирного используем <b>, а не <strong>; абзацы делаем с помощью <p>; ссылки ставим только относительные. Точно такие же соглашения существуют и в отношении кода: как ставим {скобки}, что используем для табуляции — пробелы или табы.
Соорудить надстройку над этой документацией в формате html не очень сложно: нужны индексы (предметные указатели), нужен поиск, нужны пути, нужен список последних правок, нужны специальные теги для багов и вопросов. В общем, костыли кажутся не более сложными, чем костыли для wiki.
В любом случае нужен архивариус, который будет поддерживать порядок.
