Микрорешения

Надо описывать смысл происходящего. В деталях при необходимости можно разобраться. Если надо писать много комментариев, значит, обычно, код плохой.

Рекомендации Алена Голуба:

• код без комментариев не имеет смысла
• располагайте код и комментарии вместе (правильность документации обратно пропорциональна расстоянию от кода)
• Комментарии должны быть предложениями текста.
• Пропустите свой код через программу орфографической проверки.
• Комментарий не должен подтверждать очевидное. Плохо: i++; // увеличить i на 1
• Комментарий должен предоставлять только необходимую для сопровождения информацию.
• Комментарии должны быть в блоках.
• Комментарии должны быть выровняны по вертикали.
• Используйте аккуратные столбцы везде, где можно.
• Комментарии должны иметь такой же отступ, как и код программы.
• Пустое место -- самый эффективный комментарий.

И от Кернингана с Пайком:

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

literate programmming

literate programming (не литературное!).Для фундаментальных работ. Знаю два случая применения (TeX и docbook-xsl). Это, скорее, "документация на века", а не документация к программе. С другой стороны, читать это приятно.

LP апервые появилось в TeX'e. Автор -- Кнут. Язык Web: Pascal + TeX. Утилиты:

• weave: вытаскивает документацию (например, TeX из Web)
• tangle: вытаскивает код (например, Pascal из Web)

Основная проблема: исходник обычно не является валидным. Проекту docbook-xsl проще.

LP мне кажется излишним. Имеет смысл использовать в простейшем варианте: редактор выделяет комментарии, и они читаются как текст.

JavaDoc & Co

• Комментарии специального вида.
• Описывается API.
• Стандарт для Java World.
• Несколько формален -- комментарии JavaDoc часто пишутся после.
• Успешный проект: для многих языков есть нечто аналогичное.

python docstrigns

C# metadata

Расспросить про опыт практического применения doxigen или другого средства тех, кто использовал:

• что было до xxx,
• почему решили использовать подобную систему,
• почему выбрали xxx,
• результаты
• и т.д.

"Тяжёлые" методы

Документация "на века". Single-source publishing. Reuse. Это обычно подразумавает XML (вообще-то SGML был изобретён как раз для управления документацией).

LaTeX.

DocBook. XML-стандарт. Используется во FreeBSD, ALT Linux, Samba и многих других проектах. Без поддержки со стороны редактора писать сложно. Зато из него получается HTML, HTML Help, Java Help, PDF.

Вообще-то есть профессия "технический писатель".

Часто используется FrameMaker (особенно не в программировании, а в промышленности). MS publishing использует FM вместо своей разработки.

При аккуратном использовании и Word подойдёт, но менеджер может захотеть "помочь" и всё поломается.

В любом случае нельзя делать:

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

Чем серьёзней документаций, тем более единообразно она выглядит. Достигается с помощью стилей.

Отраслевые стандарты. AECMA 1000D. Образец подхода к сложным системам.

DocBook

Эталонный XML-стандарт для написания технической документации. Любой XML-инструмент должен поддерживать его, иначе что-то у инструмента не так.

DocBook очень сложен, поэтому есть "упрощённые версии". Можно также создавать свои типы документов на основе DocBook.

Основные источники информации (помимо документации):

• DocBook: The Definitive guide <http://docbook.org/>
• DocBook XSL: The Complete Guide <http://www.sagehill.net/book-description.html>

Пакет docbook-xsl содержит стили для преобразования в:

• HTML,
• HTML Help, Java Help etc,
• XSL-FO (для создания PDF).

Есть варианты создания PDF через LaTeX (dblatex или db2latex), но они не очень работают.

LaTeX

Был TeX. К нему писали макросы. Leslie Lamport создал набор макросов LaTeX, который получил большое распространение.

Основы LaTeX -- в книгах. Одна из них есть в сети: "Не очень краткое введение в LaTeX2e".

Пример с пояснениями для тех, кто знает:

\documentclass[a4paper]{article}
\usepackage[koi8-r]{inputenc}
\usepackage[T2A]{fontenc}
\usepackage[english,russian]{babel}
\begin{document}
\title{тест}
тест
\end{document}