- Как известно, программисты, обычно, не очень любят писать документацию… поэтому чем проще и комфортнее будет её писать, тем больше вероятность, что её таки будут писать.
- Поскольку мы работаем из дома, то должна быть возможность писать документацию локально, на своей машине.
- Чтобы это было делать комфортно, нужна возможность использовать для этого любимый текстовый редактор, никаких форм на вебсайтах а-ля вики или систем заточенных под конкретный редактор/IDE.
- С доступом в инет у всех по-разному, и чтобы исключить ситуацию, когда документация небыла написана исключительно потому, что когда появилось настроение её писать по закону подлости отвалился инет — для написания документации не должен требоваться инет.
- Документация должна быть доступна всем, кто работает над проектом. Это включает как возможность читать её через вебсайт так и работать с ней как с обычными локальными файлами.
- Желательно, чтобы документация поддерживала какой-нить язык разметки и гиперссылки, чтобы её было удобно читать.
- Возможность редактировать документацию из браузера (а-ля вики) желательна, но не очень важна (разработчики будут работать с файлами, так что эта фича может пригодиться в основном клиенту, который врядли будет напрямую править документацию).
В результате, изучив существующие решения, я оставился на системе AsciiDoc. Это утилита, которая конвертирует обычные текстовые файлы (использующие очень простую и интуитивную разметку) практически во что угодно (html, docbook, man, etc.). Причины выбора AsciiDoc следующие:
- Очень простой и интуитивный язык разметки. Фактически, глядя на текстовый файл с разметкой AsciiDoc, даже не сразу догадаешься, что это не просто обычный текстовый файл, а «файл с разметкой» — он похож на обычный, аккуратно структурированный текстовый файл. По сути, я до обнаружения AsciiDoc много лет писал обычные текстовые файлы примерно в том же стиле, без всякой мысли их позже конвертировать в другие форматы! Отсутствие явной «разметки» очень облегчает чтение и редактирование текста в обычном текстовом редакторе.
- Вообще-то «правильный» формат для технической документации — это DocBook. Но писать в этом формате документацию, что ручками, что с помощью специальных утилит… бррр! А AsciiDoc умеет конвертировать в том числе и в формат DocBook. Таким образом, есть возможность написать основную часть документации в простом и удобном текстовом формате AsciiDoc, а уже потом отконвертировать в DocBook и «причесать», используя специфичные фичи DocBook, которых нет в AsciiDoc — это должно в разы ускорить и упростить написание документации, даже если её нужно сдавать в формате DocBook.
- AsciiDoc умеет сам конвертировать помимо docbook в man и html форматы, а если нужно будет что-то другое, то в любой другой формат можно сконвертировать из docbook.
- Внешний вид генерируемых html настраивается через css (впрочем, меня пока вполне устраивают и дефалтовые настройки).
- AsciiDoc достаточно маленькая, шустрая, и при этом неимоверно расширяемая утилита (впрочем, потребности её расширять у меня пока не возникло).
Далее, мной была быстренько наваяна CGIшка, которая при вызове находила внутри проекта .txt-файл с документацией, соответствующий запрошенной url, конвертировала его с помощью asciidoc в html (с кешированием html-страниц пока не изменится исходный .txt-файл) и возвращала полученный html.
В результате, сейчас система работает следующим образом:
- пишутся обычные .txt-файлы в каталоге с документацией, локально, в любимом текстовом редакторе
- между разработчиками шарятся эти файлы так же, как и исходный код проекта (патчи или svn)
- сразу после редактирования текстового файла можно зайти на соответствующую ему url, и увидеть его в html-формате (html будет перегенерирован на лету и закеширован до следующего изменения .txt)
- мы пока этого не делали, но по сути формат asciidoc не принципиально отличается от разметки используемой в вики, так что предоставить возможность редактирования документации через веб а-ля вики проблемы составить не должно
Ссылки:
- На сайте AsciiDoc можно найти полное описание его возможностей, плюс посмотреть исходники страниц самого сайта в .txt-формате (да, сайт AsciiDoc написан на asciidoc :)).
- Я составил cheat sheet. Табличка очень актуальная, т.к. возможностей у AsciiDoc дикое кол-во, а реально хватает очень небольшого кол-ва, и хочется этот краткий список иметь под рукой.
- Описание установки и настройки asciidoc, подсветки синтаксиса для Vim, и моей CGIшки для генерирования html на лету.