[docs] ALT Docs Team policy. Part 0.

[Fr. Br. George]

On Fri, Jan 14, 2005 at 01:25:54PM +0300, Alexandre Prokoudine wrote:
> >Редактор:
> >
> >        Формат текста: 
> >	
> >	Какой увидит.
> 
> Где он его увидит?
	Предполагается, что одним из фрмальных требований к модулю будет
его автоматическая конвертируемость в HTML. Ergo, на сайте. Но можно
заглянуть и в свежеобновлённый пакет, читать текст в формате разработки.

> >	
> >        Участие в ADT: 
> >	
> >	Читает опубликованную документацию и сообщает об ошибках 
> >        посредством Bugzilla(?ссылка), посредством которой взаимодействует 
> >	с сопровождающим.
> 
> А с автором он взаимодействует?
	Формально говоря, не обязан. Автор может быть сколь кгодно
занятым, сидеть в Иллинойсе и не хотеть принимать правки со всего мира.
Связь с автором держит выпускающий (если он сам -- не автор). Но никто
не мешает автору включиться в процесс, принимать BR от багзиллы.

> >	Ответственность: 
> >	
> >	Никакой (если редактор не назначен специально для подготовки выпуска
> >	документации).
> 
> Осталось уточнить, правка какого рода вносится редактором :)
	Мне кажется, любого; вопрос в том, примет ли сопровождающий это
правку, или нет. Тут вот и пригодится разделение на народного и
ответственного редактора (правки последнего -- обязательны).

> >Выпускающий(-ие):
> >
> >	Формат текста: 
> >	
> >	Форматы представления.
> 
> А точнее?
	Ты что, всего предыдущего флейма не читал? Ну кто тебе _сейчас_
ответит на вопрос, какие _точно_ у нас предполагаются форматы
представления? По-видимому, HTML для электронной документации и TeX для
печатной. Причём правки,по возможности, надо вносить в формат
разработки. Однако это, особенно в случае книжки (да ещё слегка
обрезанной, чтобы в DVD-BOX влезала) -- не всегда возможно, поэтому
здесь фигурирует формат представления.

> >	Ответственность: 
> >	
> >	Концептуальная (выпуск должен быть целостным по содержанию),
> >	эстетическая (и красивым).
> 
> Концептуальная? Не совсем понятно :)
	Поясняю: выпуск должен быть целостным по содержанию :))).
> По сути ты делаешь выпускающего редактора ответственным на возможные 
> проколы при комплектации, но офрмальн ответственность "концептуальная" :)
	Не только по комплектации, но и по общему планированию:
например, 128 разнородных глав по ; раздела в каждой, описывающих всё,
что можно -- это прокол release team.
> 
> 1. Каков стандартный механизм приведения готовых статей в соответствие с 
> реалиями жизни ALT. Пример: человек написал отличный материал, но в той 
> или иной степени привязанный к другому дистрибутиву с иной спецификой. 
> Кто конвертирует документ из одной конфессии в другую?
	Основная загвоздка -- в том, что для некстов нет autoutils:).
Поэтому смена конфессии -- не всегда оправданное действие, и часто --
довольно ресурсоёмкое. Возможно множество вариантов:
1. Некто единожды вызвался сменить конфессию тексту. В куче мы имеем
_неподдерживаемый_ исходник (неподдерживаемый, потому что обновления
этого исходника не обещано). При этом модуль некоторе время актуален,
затем устаревает (или сопровождающий выбрасывает устаревшие части) до
полного обессмысливания.
2. Некто вызывается б-м периодично сменять конфессию какому-то
стороннему тексту. Мы имеем в куче _ограничено_ поддерживаемый исхдник
(ограничено -- в том смысле, что он обновляется, но средств пропихивания
нашей редактуры в upstream не видать). Что же, тогда документ сохраняет
актуальность, но увеличивается количество работы для пары А-С.
3. Некто, совмещая роли А и С, подписывается и регулярно сменять конфессию
документу, и доводить его до модульности. При этом и исходный документ,
и его выкрест, помещаются в кучу.
4. Документ можно использовать, не сменяя конфессии, но с
комментариями/послесловием/т.п. Бонус в том, что в куче будет лежать два
текста -- автора и комментатора, обновление которых уляжется в обычный
редакторский цикл.
...
Я не считаю, что всё это следует включать в полиси. Примеры должны были
проиллюстрировать то, что номер -- не глухой, хотя и не самый простой.

> 2. Каким образом принимается решение о комплектации очередной книжки.
	``Каким образом, друг мой, ушиблен у тебя глаз? -- Да не
образом, а канделябром, за картами...'' Кроме шуток, вопрос непонятный.
Решение о комплектации книжки принимает выпускающий книжки. Каким
образом? В соответствии со своими представлениями об образе книжки.
Неужели и это надо включать в полиси? В задачу выпускающего может
входить что угодно. Например, юмористическое приложение к журналу
``Икарус'' или тематическое издание по работе с музыкой под Linux.

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