Введение

Мало сказать: документируйте! Надо ещё показать на своём опыте.

"Documentation is like sex: when it is good, it is very, very good; and when it is bad, it is better than nothing." -- Dick Brandon

Рассмотрим:

• формальная (часто является "отмазкой"),
• легковесная.

Формальная документация

По проекту. см. Брукс:

• Что: цели.
• Что: спецификпация продукта.
• Когда: график.
• По какой цене: бюджет,
• Где: расположение помещений,
• Кто: организационная структура.

Зачем нужны формальные документы:

• записывать принятые решения, сразу видны пропуски и несогласованности,
• донесение информации до кодеров,
• база знаний и контрольный список,
• инструмент в борьбе заказчиков, менеджеров и программистов.

Всеохватывающая информационнная система для управления -- утопия. Основное время менеджера -- это общение.

В Open source тоже есть большие проекты, и им нужны формальные документы. При этом её часто некому писать. Рекомендуемый минимальный набор:

• readme (название проекта, краткое описание, home page, license)
• quick start
• user's guide
• programmer's guide
• programmer's reference
• faq

"Лёгкое" документирование

Хочется: просто писать текст, как можно меньше отвлекаться на разметку, но при этом получить хороший HTML. Это можно.

ReST (restructured text, <http://docutils.sourceforge.net/>). Используется для данных заметок, очень мощный. Подходит для записи мыслей.

WiKi. "wiki-wiki" = "быстро-быстро". Инструмент для коллективной работы. Документация на сервере, любой из разработчивок может что-то написать или дописать. Межстраничные ссылки появляются автоматически. Есть история изменений.

База знаний: кто-то разобрался с некой проблемой и хочет поделиться своими знаниями. Как это сделать? В форуме, в рассылке затеряются среди вопросов. Ответ: wiki.

Незаменимый инструмент наравне с cvs и bugzilla.

В коммерческих проектах: даже менеджеры в состоянии быстро разобраться с wiki.

Есть разные реализации. phpwiki вполне хорош.

Возвращаемся к общему случаю. Набор необходимых средств:

• заголовок,
• абзац (paragraph),
• список,
• выделение слова,
• ссылка

Блочные эдементы. Они разделяются пустой строкой. Ещё раз: заголовок и параграф разделяются пустой строкой, абзацы разделяются пустой строкой и т.д.

После знака препинания идёт проблел. Буква, знак, пробел, ни в коем случае не буква, пробел, знак. Некоторые предпочитают ставить два пробела после точки.

Список. Строки начинаются с '*'. Или с '#' для нумерованного списка. Иногда можно использовать цифры.

Считается, что bold и italic использовать нехорошо. Поэтому вместо них используется strong и emphasis. В печатной продукции в основном используется emphasis, для веба -- strong. Mozilla (и phpwiki) понимает *text* как strong и _text_ как emphasis. На самом деле, в минимум входит только monospace для выделения имёт идентификаторов.

Отвлечение на mozillу и почту: "начало строки, минус, минус, пробел, конец строки" начинает подпись. Хорошие почтовые клиенты это знают.

Ссылки обычно распознаются автоматически.

Всё остальное -- в документации на конкретные продукты.