Документация, Часть I

Спецсеминар "Разработка свободного ПО": http://uucode.com/oss2004/. 8-я лекция, 30 октября.

Введение

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

"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 тоже есть большие проекты, и им нужны формальные документы. При этом её часто некому писать. Рекомендуемый минимальный набор:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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