[docs] ВНИМАНИЕ: отчёт и насущные проблемы

[Fr. Br. George]

On Tue, Jan 11, 2005 at 03:16:56PM +0300, Kirill Maslinsky wrote:
> 
> Модули
> ======
> 
> Всё вышеизложенное неминуемо подводит к понятию _модуля_ документации 
> ALT. Модуль -- это документ
> 
> - который взят из "кучи" исходных текстов;
> - у которого есть ответственный сопровождающий;
> - который удовлетворяет формальным и содержательным требованиям, т. е. его 
>   можно без дополнительной обработки включать в состав документации;
> 
> К сожалению, принятый в DOCS формат docbook очень существенно ограничивает 
> круг потенциальных мантейнеров. Напомню, в нём около 400 тегов. 
> Мантейнер документа -- это специалист в соответсвующей области, 
> поэтому ему нужен такой документ. Но он вовсе не специалист в docbook, 
> и, в сущности, не обязательно должен им становиться, чтобы довести 
> текст до нужной адекватности и обеспечить необходимую _логическую_ разметку.
> 
> => Нужен такой формат разметки, в котором будет различаться ровно 
> столько сущностей, сколько нужно, чтобы получились адекватные макеты
> и гипертекстовые документы. Этот формат может быть любым, единственный
> критерий: он должен быть очень небольшим, поддаваться изучению за 
> 15 минут. Как показывает практика, 7--12 тегов будет достаточно для 
> разметки документации ALT. 
	Альтернатива "усечённому" фаормату -- организация оперативной
работы "машинисток". Машинистка (она же техпис) -- это персонаж, в
совершенстве владеющий docbook, и выполняющи работу по преобразованию
текста, отвечающего только содержательным требованиям в текст,
отвечающий также и формальным, а возможно, и в обратную сторону.

	К сожалению, ситуация в ALT на сегодня такова, что содержать
штат машинисток нам не по карману (и, скорее всего, никогда не будет).
Тому виной не денежное положение, а предполагаемый объём работ. Если
вообще не использовать редакторский цикл, он занимает не менее, чем
человеко-квартал (так как Кирилл весьма часто трудится именно как
машинистка). В самом тупом варианте, когда циклов редактирования будет
два-три, мы получаем человеко-год, что означает двух машинисток: одну
-- на полную занятость, другую -- на тушение пожаров. Если же мы не
хотим затруднять обратную связь с авторами, редакторских циклов будет
существенно больше. И тогда машинисткам кранты.

	Встаёт вопрос об автоматизированной машинистке. Народ спасается
введением разнообразных wiki. Результат -- у этого народа замечательная
и актуальная документация, но только в формате HTML. Что-либо бумажное
из этого получается очень грустное, так как все известные мне
wiki-документы размечаются не структурно, а с точки зрения внешнего вида
и гипертекстовости.

	Что нам нужно -- некоторый аналог wiki-формата, но
ориентированный на получение docbook, а не HTML. Но прежде, чем делать,
надо подумать, без чего документ структурно обойтись не может, а что
можно вынести во внешний контекст.

-- 
			George V Kouryachy (aka Fr. Br. George)
			mailto:george at altlinux_ru