AsciiDoc - Задокументируй ЭТО!

Где отчет по загрузкам фиговины с хреновины за последний месяц? Мы его 26 секунд назад должны были послать! Заказчик в потолок кричит уже!

Или нет, лучше вот так:

Вот написал я совершенно шикарную (по моему скромному мнению) штуковину. Всем хороша штуковина: может делать так, а может делать сяк. Выложил я эту штуковину в интернет, а народ возьми и начинай спрашивать: а как этой штуковиной пользоваться-то? Где руководство пользователя, администратора и еще кого-нибудь?

Да не вопрос! Открыл новую вкладку в IDE, вдохновился и описал свой шедевр. Вернее, попытался описать. Диаграммку надо вот тут вставить, а вон там без скриншота не обойтись...

Так, добавляем нужные теги в файл, меняем его расширение в html. Все, готово! Еще надо в PDF? Ставим виртуальный принтер и печатаем на него. Как картинки поехали? Переносим написанное в Word или LibreOffice. Заказчик зубчиками недоволен? Данные для диаграмки поменялись? Скриншотик поменять надо? А-а-а-а … Отвалите от меня! Все, нету больше документации! Вон остатки валяются, пусть технический писатель мучается, ему за это деньги платят!

Знакомо? Думаю да. Любой, кто прикасался к описанию чего-либо, готов часами материться от совместимости форматов, стилей, шрифтов и прочих ужасов. А если подобное надо делать регулярно и еще совместно с кем-нибудь...

Все, мощнейшая демотивация обеспечена. А это неправильно. Тут я пишу про обратное, поэтому нефиг тут. Будем исправлять ситуацию.

Итак, за основу я предлагаю взять asciidoc. Есть для всех платформ и четко следует unix-идеологии выполнять хорошо только одну задачу. На входе обычный текст, а на выходе, особенно с использованием других программ, что угодно: от разметки для какой-нибудь wiki до pdf. После краткого просмотра команд становится непонятно, а почему раньше этим не пользовался...

Взято отсюда:

http://blog.kaloshin.ru/2012/11/12/Задокументируй-ЭТО/

Еще ссылки:

http://iportnov.blogspot.ru/2011/03/asciidoc-docbook.html

http://habrahabr.ru/post/12903/

http://en.wikipedia.org/wiki/AsciiDoc

Онлайн генератор:

http://andrewk.webfactional.com/asciidoc.php

Используется в т. ч. издательством O'Relly.

От себя: неплохая вещь, удалось установить под Windows в Cygwin и прикрутить к Sublime Text. PDF удачно сгенерировался через dblatex.

А как вы документируете проект? Или у вас ситуация, описанная самом начале топика?