[docs] проблемы модульной документации

[Stanislav Ievlev]

Модули alterator постоянно обновляются, поэтому я предлагаю следующий подход:
1. С каждым современным модулем распространяется документация в
html-формате. Ожидается, что она будет всегда более менее актуальна. Это
есть краткая информация по интерфейсу и функционалу модуля.
2. Отдельно предлагаю хранить документацию общего характера, не сильно
зависящую от интерфейса и в основном поясняющая суть того или иного
процесса.
3. Дождавшись как можно ближе deadline можно сделать слияние этих двух
кусков и результат выпускать как уже цельную книжку: и актуальную и
информативную.

On Sun, Jun 17, 2007 at 07:22:45PM +0300, Artem Zolochevskiy wrote:
> Господа,
> 
> Давайте как-то приходить к решению вопроса именования моделей/пакетов с 
> оглядкой на их присутсвие в документации к конкретным дистрибутивам.
> 
> Конкретно я вот о чем:
> 1. По идее тот или иной модуль документации должен отражать текущее состояние 
> дел по описываемой теме.
> Пример:
> Модуль документации alterator_x11.kirill описывает поведение alterator-x11.
> Само собой сам alterator-x11 развивается и по идее alterator_x11.kirill должен 
> поспевать за ним. Тут проблем нет.
> 
> Проблема:
> на момент выхода 3.0 alterator_x11.kirill описывал (и это соответствовало 
> тогдашней дейсвительности) поведение тогдашнего alterator-x11. В таком виде 
> это и вошло в прилагаемую к дистрибутиву документацию.
> сейчас выходит 4.0 и  alterator_x11.kirill  будет уже несколько иным 
> (соответсвующим нынешнему состоснию  alterator-x11)
> Проблемы возникает при желании иметь одновременно документацию на 3.0 и 4.0 
> (ну, к примеру, я использую Сизиф). Т.е. модифицируя alterator_x11.kirill для 
> 4.0 у меня автоматически "ломается" документация на 3.0
> 
> Похожие параллели можно провести и между server и desktop. У них "разъехались" 
> инсталляторы и по факту install0.kirill описывает именно server-ный вариант. 
> Опять же если его модифицировать для desktop, то неясно, как иметь под рукой 
> одновременно документацию по server и desktop.
> 
> Особых идей у меня нет, но принципиально видится вот что...
> 1. Смириться с тем, что к примеру, в Сизифе невозможно иметь докуменацию на 
> тот или иной выпуск дистрибутива (в том же виде в котором она туда попала).
> Ну не искать же в архиве именно те версии что были тогда и ставить их 
> вручную... 
> Очевидно, что этот вариант работает при условии разделения репозиториев. 3.0 
> отдельно, 4.0 - отдельно, 5.0 - отдельно ;-)
> Получить документацию на конкретный дистрибутив из Сизифа в этом случае 
> _невозможно_. Тогда нужно помнить, что все docs-issue-...  в Сизифе отбражают 
> документацию непонятно на что. Потому как совсем непонятно какие версии 
> модулей, составляющих конкретный docs-issue- установлены.
> 2. Продумать систему именований модулей/пакетов, чтоб они соответсвовали тем 
> дистрибутивам, к которым они писались, что позволит иметь паралельно 
> установленную документацию относящуюся к разным выпускам.
> 
> Нынешнее состояние дел, совсем запутанное.
> Есть модули, в именовании которых фигурирует название дистрибутива 
> (whatis_compact3.0-kirill), есть "универсальные" - тот же 
> alterator_users.kirill (проблемы с таковыми я описал выше), а есть такие, 
> которые вообще сами по себе, и не особо связаны с конкретным выпуском - 
> unix_and_internet_fundamentals_howto.kvas
> 
> Плюс к этому есть
> docs-issue-...
> которые тоже не совсем понятно как именуются (версионируются). вернее понятно 
> как, непонятно почему вразнобой.
> docs-issue-desktop (версия пакета 4.0)
> docs-issue-server (версия пакета 4.0)
> docs-issue-compact3.0 (версия пакета 0.3)
> 
> Как я понимаю, документация стала модульной не так давно -- со времён 3.0 и 
> может ещё просто эти вопросы не устоялись.
> Давайте чем-то порешим, либо просто растолкуйте что к чему.
> С Кириллом я немного тему обсуждал, но всё-же, согласитесь, ситуация несколько 
> запутанная.
> 
> Кто что скажет?
> 
> PS.
> Как всегда куча опечаток... извините.
> 
> --
> Артём Золочевский
> _______________________________________________
> docs mailing list
> docs на lists.altlinux.org
> https://lists.altlinux.org/mailman/listinfo/docs