[docs] требования к формату модуля документации

[Kirill Maslinsky]

Ещё раз всем привет. 
Продолжение. 

Требования к разметке модуля DOCS 
=================================

DocBook не очень годится в качестве формата для модуля документации в 
DOCS: он слишком велик (около 400 элементов), требует долгого и 
внимательного изучения. Кроме того, многие полагают разметку в 
XML неудобной. 

Задача: разработать (или выбрать) формат, в котором
будет вся необходимая и достаточная логическая информация для 
сборки конечных форматов. 

Постулат: такой формат может и должен содержать не более 7--12 элементов.

Необходимые и достаточные условия для сборки конечных форматов 
из модуля документации я попробовал сформулировать ниже.

Необходимая информация
----------------------

Для автоматического получения корректных документов в конечных 
форматах, в модуле документации DOCS необходима информация:

- об авторе(ах);
- языке(языках) текста (чтобы выбрать правила переносов);
- заглавие;
- ID для текста и всех элементов текста, на которые есть гиперссылки.
  Желательно иметь ID для всех подразделов документа, чтобы на любой из
  них можно было ссылаться впоследствии.
  Требования к ID:
  + уникальный в рамках всего массива документации (всех модулей);
  + единообразные (образованные по единым правилам);
  + умопостижимые (удобные для чтения и написания, гиперссылки ставят люди);
В приниципе, если ставить гиперссылки только на подразделы, в качестве ID 
можно использовать название документа+название подраздела. Это вряд ли 
повлечёт случайные совпадения, и позволит ID генерить автоматически.


Содержательные требования
-------------------------

* Разумная (стандартная) структура.

Понятие "разумная структура" весьма интуитивно, однако ряд положений 
можно сформулировать:

- Адекватное членение текста на подразделы. Они не должны быть слишком 
  мелкими или слишком длинными. Не должно быть слишком много уровней
  вложенности разделов. В принципе, 3-х должно быть достаточно, 4 -- для 
  очень больших и подробных документов.
- Не должно быть слишком глубоко вложенных списков; желательно не более 
  3-х уровней вложенности.
- Адекватное членение текста на абзацы: нехороши слишком длинные и 
  слишком короткие абзацы.
- Соблюдение некоторой стандартной структуры документа: если решим делать 
  abstract'ы, то уж всем текстам, а если не делать -- тоже у всех. Возможны
  необязательные разделы, например, библиография, глоссарий, указатель и т. п. 
  Стандартную структуру нужно сформулировать.

* Модульность изложения.

Изложение должно быть относительно независимо от контекста, критерий: чтобы
текст данного модуля можно было без потерь переставить в другой раздел 
документации. Все ссылки на текст других модулей должны быть оформлены 
в виде явных и работающих гиперссылок.

* Корректность фактической информации.

Сюда относятся все вопросы содержательной адекватности документа тому
программному обеспечению, которое он описывает, его up-to-dateness. 
В общем виде документ должен быть проверен на соответствие тем версиям 
ПО, с которым он поставляется (например, в составе дистрибутива). Частности:
- Версии пакетов
- Формат конфигурационных файлов
- Примеры командной строки (опции и пр.) и т. п. 

Кроме того, все ссылки на внешние ресурсы (URL, книги, другие модули документации) должны быть рабочими.

Проверку некоторых из перечисленных пунктов можно автоматизировать.

* Соблюдение стандартной терминологии.

Упирается в составление глоссария терминов. 

Требования к формату
--------------------

Исходя из перечисленных условий, а также из требований, накладываемых 
необходимостью подготовить печатный формат (см. письмо с сабжектом 
"отчёт и "), можно сформулировать, какие примерно теги для 
разметки нужны в искомом формате.

+ Теги секционирования. Заголовок и подразделы. Должно быть достаточно 3--4
  уровней вложенности.

+ Теги для списков. Нумерованных и ненумерованных, в несколько уровней.

+ Теги для оформления "цитат из системы": имён файлов, пакетов, URL, примеров командной строки. Необходимы, т. к. к ним нужно применять специальные 
правила переноса.

+ Теги для оформления текстовых примеров в несколько строк (набираются не 
прямо в тексте абзаца, а в виде плавающих объектов или отдельных абзацев). 
Внутри текстовых примеров должен быть способ указать (специальный тег)
допустимые точки для разрыва строк, чтобы можно было сверстать примеры на 
узкий формат автоматически. Более того, в текстовых примерах, ширина строки
в которых больше, чем XX символов, такие точки _обязательно_ должны быть
указаны.

+ Тег для включения изображений (с подписью).

+ Тег для включения таблиц с подписью (формат таблиц остаётся под вопросом).

+ Тег (теги) для гиперссылок: на разделы документа и другие документы, 
на URL. Возможно, эти теги могут служить для ссылок на любые внешние 
и внутренние ресурсы, например, книжки в библиографии.

+ Тег для оформления важных замечаний, которые должны быть выделены 
графически в конечных форматах.

+ Тег (теги) для комментариев. Если в этом формате предполагается 
взаимодействие с редактором -- то для редакторских заметок.

Как будто бы и всё.

Жду комментариев и предложений подходящих форматов.
-- 
Kirill Maslinsky
ALT Linux Team * Documentation Project