[docs] далее о docs-alterator

[Kirill Maslinsky]

On Sun, Jul 15, 2007 at 11:40:49PM +0300, Artem Zolochevskiy wrote:
> Так как обсуждение целей docs-alterator* чуть выше заглохло, то опишу как я 
> себе вижу ситуацию.
> 
> Модули alterator-* встречаются как в виде "Центра управления системы" так и в 
> виде шагов инсталлятора. Причём надо заметить, что в инсталляторе они могут 
> иметь несколько иную компоновку (табы и т. п. -- см. настройки сети).
> 
> Есть docs-alterator* , призванные описать соответсвующие alterator-* модули. 
> Вопрос в том, может ли текст docs-alterator-* быть  универсален и для 
> прочтения его в контексте инсталлятора и в контексте Центра управления 
> системы? Мне думается, что, конечно, может, но это привносит определённые 
> трудности при составлении текста.

У меня был опыт использования одних и тех же текстов для справки модулей
инсталлятора и для документации -- compact 3.0. В итоге к моменту релиза справка
и модули документации уже были разными текстами (причем это сложилось
само собой, иначе не получалось). В результате этого
опыта сложилось впечатление, что попытка убить одним текстом двух зайцев
приносит больше проблем, чем выгод. 


> Пример: docs-alterator_network-kirill. Вот этот модуль замечательно читается в 
> контексте Центра управления системы, но не очень хорошо в контексте 
> инсталлятора. Уже по той причине, что спрева речь об общих сетевых 
> настройках, а затем о IP-интерфейсах. А в инсталляторе они идут как раз в 
> обратном порядке. Или модуль docs-alterator_users-kirill: Замечательно 
> читается в контексте инсталлятора, но вот при применении его для описания 
> модуля Центра управления уже могут возникнуть недопонимания. Ну нет там (в 
> Центра управления) ничего про root.
> 
> С другой стороны, с привнесением скриншотов в документирование инсталлятора, 
> docs-alterator-* окончательно теряют даже ту универсальность, которую имеют.
> 
> Что будем делать?

Нужно посмотреть, где используются модули docs-alterator-* в
документации. Прежде всего, это руководство по установке. Раз 
пошла такая история, что в каждом дистрибутиве даже один и тот
же модуль может выглядеть по-разному, плюс он обязательно выглядит
по-разному из-за дизайна, то можно сделать описание процесса установки
одним большим модулем. И для каждого дистрибутива изготавливать
самостоятельные версии на основе этого модуля (тут нужно подумать,
как это лучше организовать, но git нам точно поможет).

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


> Что я вижу:
> * docs-alterator-* дублируют справку web-конфигуратора.
> * описания  alterator-* , встречающиеся на стадии установки получают какие-то 
> имена не пересекающиеся с docs-alterator*
> 
> Какие есть минусы:
> * docs-alterator-* вроде как задумывались не как "справка" а 
> как "разъяснительная документация"
> 2kirill: можешь тут подробнее?

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

Вот документация лучше пусть будет более общей и по возможности 
вообще отвязанной от интерфейса (а то придется ее переделывать
для каждого варианта). Если в модуле docs-alterator-* нечего сказать,
кроме описания интерфейса модуля, то следует задаться вопросом: 
нужен ли этот модуль в документации вообще?


> 
> Плюсы:
> * А может и "справка" web-конфигуратора с удовольствием 
> станет  "разъяснительной документацей" и тогда от их объединения все только 
> выиграют?
> * решение проблемы "скриншотов"
> 
> Кто что мыслит?
> 
> -- 
> Артём Золочевский
> _______________________________________________
> docs mailing list
> docs на lists.altlinux.org
> https://lists.altlinux.org/mailman/listinfo/docs

-- 
Кирилл Маслинский
Альт Линукс
руководитель издательских проектов
http://heap.altlinux.ru