DocBook: системный подход к документации

Анатолий Белайчук

Мария Николаева

Надежда Матвеева

Станислав Фридкин


Содержание

1. Беглый взгляд
2. Инструментарий
3. Настройка
4. Выходные форматы
5. Для технического писателя
6. Для коллективной работы
7. Контент, дизайн и структура
8. Тотальное документирование
9. XML-стратегия

Аннотация

Технология DocBook существует с 1991 года и к сегодняшнему дню принята на вооружение многими лидерами ИТ-отрасли. Достоинства этой основанной на XML технологии — независимость от конкретного поставщика, открытость для расширений, отделение контента от дизайна и, не в последнюю очередь, свободно распространяемый инструментарий. Особый интерес DocBook представляет для организаций, стремящихся к систематическому документированию своей деятельности.

Наблюдательный посетитель Internet может обнаружить в Сети множество документов с однотипной навигацией между страницами при помощи ссылок Prev, Next, Up, Top, причем один и тот же документ может предлагаться в нескольких форматах: каскадный HTML, единый HTML, PDF.

Рисунок 1. Документация Samba (www.samba.org)

Документация Samba (www.samba.org)

Возникает подозрение, что документы в разных форматах генерируются автоматически из одного источника. Из какого? Чтобы это узнать, заглянем в код HTML:


<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>The Official Samba-3 HOWTO and Reference Guide</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.61.1"1>

1

Свидетельство того, что HTML-страница сгенерирована XSL-скриптами DocBook.

Копнув еще глубже, обнаруживаем, что DocBook используют многие авторитетные компании:

На DocBook написана документация на Linux (www.tldp.org), FreeBSD (www.freebsd.org), Sun Solaris (docs.sun.com), PHP (www.php.net).