[docs] Re: webcvs

[Kirill Maslinsky]

> > Совершенно согласен, не техническая. Собственно, и возможности
> > cvs по управлению ветками и пр. не требуются и не должны
> > использоваться в документации.
> 
> А, собственно, почему? Рассмотрим такие простые примеры:
> 
> 1) Есть некий большой текст и его надо серьёзно переработать. При
> неиспользовании веток мы либо верменно "ломаем" документацию либо
> лишаем автора естественного способа взаимодействия с редактором
> (человеком, а не программой), критиками, да и собсвтвенно
> возможности откатиться на некое промежуточное состояние.

Хм, это надо обдумать. Однако вышеописанная ситуация мне всё же кажется
немного натянутой: 
1) реальная "работающая" документация 
содержится в пакетах, а не в cvs, поэтому "ломая" текст в cvs мы 
никак его не портим в дистрибутиве. А cvs и нужен для разработки. 
2) если текст нужно серьёзно перерабатывать, это означает, что либо 
он плохого качества, иначе говоря, по природе своей "сломан" и в
документации в таком виде появляться не должен. Либо это означает, 
что на основе данного текста нужно сделать другой текст для _другого 
продукта/проекта_ -- в таком случае следует не ветку организовывать, 
а создавать новый профиль для нового продукта (раз он так отличается,
что требует кардинальной переработки текста) и спрофилировать дерево
документации на уровне разделов. Соответственно, текст дублируется 
с другим профилем и там перерабатывается. Вообще такой вариант мне 
тоже кажется маловероятным, скорее всего в последнем случае будет 
достаточно профилирования на уровне абзацев.
3) почему изменения, вносимые в текст лишают автора способа
взаимодействия с редактором я, признаться, просто не понял. 

> 2) Грамотное использование веток позволяет одноверменно вести
> доработку доукументации выпущенных продуктов (например, исправить
> ошибки/дополнить текст для дополнительного тиража) и вести
> разработку вперёд.
Не считаю, что доработка и разработка вперёд в случае документации -- 
это разные задачи. Отнюдь. Сейчас значительная часть документации -- 
общие разделы, которые применимы к любому дистрибутиву практически. 
Любые исправления и дополнения в них -- на пользу и уже выпущенному 
продукту и будущим. Если с изменением версий программ изменяется
синтаксис и т. п. это опять же решается профилированием на уровне
абзацев.

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

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


PS отличный получается образ, что редактор, это человек, который
_ломает_ текст. текст ощущается как деревянный, но это уже от автора 
зависит ;) 

-- 
Kirill Maslinsky
ALT Linux Team * Documentation Project