Введение

С тех далеких времен как был изобретен язык разметки XML, он успел проникнуть во все сферы нашей повседневной компьютерной жизни. Мы его уже практически не замечаем; или по крайней мере старательно делаем вид. Вот тут он используется для хранения конфигурационных данных, а здесь он используется для удаленного вызова процедур (XML RPC). А вот тут он уже во всю стал основой для XHTML.

Эти три буквы, изменившие мир, можно любить или ненавидеть. Но есть, как минимум, одна область IT, в которой XML произвел не только переворот сравнимый по масштабности с революцией, но и стал его непоколебимым фундаментом. Я говорю о создании и поддержке документации.

Вы же ведь слышали о DocBook или fb2, не так ли?

Внимание: в статье присутствует графический материал.

Когда перед нашей фрилансерской группой встала задача документирования проекта, были сформулированы следущие требования:

• Как известно, программисты, обычно, не очень любят писать документацию… поэтому чем проще и комфортнее будет её писать, тем больше вероятность, что её таки будут писать.
  
  • Поскольку мы работаем из дома, то должна быть возможность писать документацию локально, на своей машине.
  • Чтобы это было делать комфортно, нужна возможность использовать для этого любимый текстовый редактор, никаких форм на вебсайтах а-ля вики или систем заточенных под конкретный редактор/IDE.
  • С доступом в инет у всех по-разному, и чтобы исключить ситуацию, когда документация небыла написана исключительно потому, что когда появилось настроение её писать по закону подлости отвалился инет — для написания документации не должен требоваться инет.
• Документация должна быть доступна всем, кто работает над проектом. Это включает как возможность читать её через вебсайт так и работать с ней как с обычными локальными файлами.
• Желательно, чтобы документация поддерживала какой-нить язык разметки и гиперссылки, чтобы её было удобно читать.
• Возможность редактировать документацию из браузера (а-ля вики) желательна, но не очень важна (разработчики будут работать с файлами, так что эта фича может пригодиться в основном клиенту, который врядли будет напрямую править документацию).