[docs] форматы/проблемы выпусков

Artem Zolochevskiy artem.zolochevskiy на gmail.com
Пт Авг 17 14:06:24 MSD 2007


hi all

Оправившись от шока выпуска Desktop 4.0 Personal немного прихожу в себя и 
пытаюсь привести мысли в порядок.

Вот какие возникли размышления/вопросы.

0. Я ничего не имею против модульности документации. Но реальный опыт (хоть и 
малнький) показал, что модули хороши просто как отдельные тексты, на разные 
темы.
1. Модульность может и хороша, но явно не для изготовления "выпусков". Имеется 
ряд проблем, о которых я уже писал (например использование в одном выпуске 
дважды одного модуля). Надо либо фиксить эти проблемы либо что-то менять в 
корне. Ещй одна проблема -- это разрозненность форматирования выпуска, 
получаемого из кучки модулей. Я пришёл к тому, что не стоит дробить к примеру 
реководство по установке. Это должен быть явно один цельный модуль. Похожая 
история с модулями по разбивке/организации диска. Непонятно зачем они 
выполненыо отдельными модулями, если они по отдельности всё равно не живут 
(каждый их них имеет ссылку на другой модуль). Т.е. вот ещй одна проблема: 
ссылки в модулях на другие модули. По идее их не должно быть вообще. Модуль 
мне представляется как нечно цельное и самодостаточное. Иначе включение в 
выпуск одного модуля _неизбежно_ тянет за собой необходимость другого (на 
который первый имеет в тексте ссылки).
2. Был ли опыт создания "выпусков" полностью состоящих из DocBook. Если да, то 
какие подводные камни всплыли и почему отказались.
3. Мне DocBook (который я только-только начал рассматривать/изучать) показался 
приятным с точки зрения создания printable версий. Как мне кажется, 
использование этого формата решит также и проблему отсутсвия исходников 
печатных версий документации, которые (печатные версии) как мы знаем/видим 
немного, да отличаются от html-версии.


Одним словом хочется обозначить проблему с "выпусками":
- при создании выпусков они получаеются весьма корявые по части 
форматирования, да и по "связности" повествования, ибо делаются из 
разных "кусков" притянутых друг к другу. Тут надо просто не "мельчить" и 
как-то прийти к общему форматированию. Т.е. делать здоровенные 
модули: "установка", "руководство пользователя".
- нет интструментов получения printable версии. Как я понимаю, в лучшем случае 
в руки берётся tex, в худшем OpenOffice
- нет исходников печатных руководств

Кто/что может вообще сказать по инструмаенам документирования?
Как я понимаю DocBook успешно используется к примеру в Debian, FreeBSD и т. п.

Обладает ли кто-то вообще обзором по существубщим форматам/интрументам работы 
с документацией? Очень хотелось бы выслушать, чтоб самому не ходить по 
граблям.

-- 
Артём Золочевский


Подробная информация о списке рассылки docs