|
0
Bugmenot
12.06.13
✎
16:05
|
Всего мнений: 3
Где отчет по загрузкам фиговины с хреновины за последний месяц? Мы его 26 секунд назад должны были послать! Заказчик в потолок кричит уже!
Или нет, лучше вот так:
Вот написал я совершенно шикарную (по моему скромному мнению) штуковину. Всем хороша штуковина: может делать так, а может делать сяк. Выложил я эту штуковину в интернет, а народ возьми и начинай спрашивать: а как этой штуковиной пользоваться-то? Где руководство пользователя, администратора и еще кого-нибудь?
Да не вопрос! Открыл новую вкладку в IDE, вдохновился и описал свой шедевр. Вернее, попытался описать. Диаграммку надо вот тут вставить, а вон там без скриншота не обойтись...
Так, добавляем нужные теги в файл, меняем его расширение в html. Все, готово! Еще надо в PDF? Ставим виртуальный принтер и печатаем на него. Как картинки поехали? Переносим написанное в Word или LibreOffice. Заказчик зубчиками недоволен? Данные для диаграмки поменялись? Скриншотик поменять надо? А-а-а-а … Отвалите от меня! Все, нету больше документации! Вон остатки валяются, пусть технический писатель мучается, ему за это деньги платят!
Знакомо? Думаю да. Любой, кто прикасался к описанию чего-либо, готов часами материться от совместимости форматов, стилей, шрифтов и прочих ужасов. А если подобное надо делать регулярно и еще совместно с кем-нибудь...
Все, мощнейшая демотивация обеспечена. А это неправильно. Тут я пишу про обратное, поэтому нефиг тут. Будем исправлять ситуацию.
Итак, за основу я предлагаю взять asciidoc. Есть для всех платформ и четко следует unix-идеологии выполнять хорошо только одну задачу. На входе обычный текст, а на выходе, особенно с использованием других программ, что угодно: от разметки для какой-нибудь wiki до pdf. После краткого просмотра команд становится непонятно, а почему раньше этим не пользовался...
Взято отсюда:
Еще ссылки:
Онлайн генератор:
Используется в т. ч. издательством O'Relly.
От себя: неплохая вещь, удалось установить под Windows в Cygwin и прикрутить к Sublime Text. PDF удачно сгенерировался через dblatex.
А как вы документируете проект? Или у вас ситуация, описанная самом начале топика?
|
|
