Документация II

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

В "документация-I" говорили об:

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

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

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

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

literate programmming

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

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

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

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

JavaDoc & Co

python docstrigns

C# metadata

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

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

Документация "на века". 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-xsl содержит стили для преобразования в:

Есть варианты создания 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}