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

[Fr. Br. George]

On Wed, Jan 12, 2005 at 12:35:32AM +0300, Vitaly Ostanin wrote:
> 
> И опять повторю. IMHO, нет в этом письме насущных проблем - всё 
> то же отсутствие удобного редактора. Даже pdf вывод уже решается 
> 3-мя вариантами, а вот редактора нет. И не надо форматы 
> изобретать на зависть комитету DocBook - всё те же проблемы с 
> редакторами будут, которые не vi/emacs.
	И опять повторю: удобных редакторов полным-полно. Каждый автор
работает именно в удобном ему редакторе. И майнтейнер документа --
человек, разбирающийся в предмете, а не в форматах -- работает именно в
удобном ему редакторе. Тем более, чо в идеале эти роли совпадают (просто
из соображения удобства работы).

	Прошу нижеследующее понимать, как проект WorkFlow.

	Я не считаю, что наша задача -- заставить ldv, cray или ab
ползоваться удобным (по мнению одного или даже большинства из docs)
редактором или форматом. Более того, я абсолютно уверен, что это никому
не удастся. С другой стороны, поддерживать документацию в актуальном
состоянии несравненно легче, если правки вносятся в формат разработки, а
не в авторский. Отсюда вывод: либо при _каждом_ изменении документа
автором майнтейнер проделывает трёхкратно полную работу (перевод в
формат разработки, редактирование, перевод в авторский формат), либо эти
форматы должны быть близки до степени (полу)автоматического переводя
туда и обратно.
	В первом случае -- покажите мне этого фаната. Во втором --
проделывается подмена -- заметная, но не тотальная. Привык писать в
plain text -- вот тебе wiki-подобный синтаксис, привык в HTML (были
такие пожелания) -- вот набор HTML-тегов, которые надо использовать,
привык в DocBook -- замечччательно, вот набор тегов DB. Даже для
M$Word/OOo можно написать двусторонний конвертор -- при условии,что
автор будет соблюдать некутороую дисциплину разметки.
	Бонус от этого мероприятия один, и он, по идее, должен закрывать
проблему действительно насущную: вся правка делается в формате,
доступном пониманию автора. Если человек присылает чистый текст,
майнтейнер отсылает ему wiki-образный текст со словами: "если захочешь
править, правь _это_, вот _несложные_ правила оформления". То же самое с
HTML, DB, ... что придумается ещё. Причём останется тлько приладить
конвертор в HTML и выложить на сайт -- и вот тебе прямой повод для
обратной связи, для Багзиллы.
	Это означает, что к релизу -- опять-таки, в идеале, остаётся
только комбинаторная и чистовая работа, с которой вполне может
справиться release team даже из одного человека. При этом дополнительный
бонус -- в том, что доводка _несложного_ формата до пригодного к печати,
изящного HTML-я и т. п. вполне автоматизируема, а неизбежная ручная
работа (мнение выпускающего о том, как должен на самом деле выглядеть
документ), вполне пригодна для back propagation, для внедрения в
документ в формате разработки.

	Итого.

	Имеется четыре роли: автор, сопровождающий (maintainer),
выпускающий (release manager) и редактор из народа. Роль автора и
сопроводающего может совпадать; никому не возбраняется выступать в роли
редактора.

Автор:
	Формат текста: ``любой'' (лучше -- конвертируемый в формат
		разработки ALT, ещё лучше -- конвертирумый в обе стороны)
	Участие в ALD: заливает тексты в ``кучу'', взаимодействует (если
		хочет) с сопровождающим.
	Ответственность: при заливке текста в ``кучу'' описать его так,
		чтобы этим вообще можно бвло пользоваться. Более никакой.

Сопровождающий:
	Формат текста: формат разработки ALT
	Участие в ALD: берёт текст из ``кучи'' и превращает его в
		модуль. Взаимодействует со всеми остальными персонажами.
	Ответственность: содержательная (исправление автора и
		обновление), и формальная (требования к формату; из
		модуля должен собираться HTML для просмотра народом)

Редактор из народа:
	Формат текста: какой увидит :)
	Участие в ALD: читает документацию и сообщает об ошибках в
		Багзиллу, чем взаимодействует с сопровождающим.
	Ответственность: никакой (если редактор не назначен начальством
		для чистки перед релизом или для литредактуры).

Выпускающий(-ие):
	Формат текста: форматы представления
	Участие в ALD: составляет общий план документации и собирает её
		из модулей. Доводит формат представления до приемлемого
		уровня. Взаимодействует со всеми, пинает нерадивых.
	Ответственность: концептуальная (должна быть документация, а не
		свалка), эстетическая (должно прилично выглядеть).

Комментарии?

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

P.S.	А комитет по DocBook явно решал какие-то другие задачи...