[docs] Documentation source repository (was: [devel] ALT packaging docs)

[Kirill Maslinsky]

Всем добрый день!

Очень кратко суть предложения: 
Речь о том, чтобы разделить в проекте docs
поддержку авторами исходных текстов документов и поддержку DocBook-версий
непосредственными участниками проекта docs. Для этого организовать 
репозиторий исходный текстов документации, куда авторы могут отправлять 
текст в любом удобном им формате и поддерживать этот текст в актуальном 
состоянии (в этом же формате). Модель взаимодействия -- наподобие INCOMING.

Мотивировка решения: 
Для огромного большинства авторов DocBook -- препятствие для участия 
в проекте, но они готовы писать, и, что, может быть, важнее, поддерживать
тексты. В то же время есть люди, которые умеют и готовы делать из этих текстов
DocBook, редактировать и т. д.

Ниже следуют выдержки из дискуссии в devel@, которая развернулась вокруг 
предложения включить и поддерживать в ALT Docs (пакете alt-docs-devel)
все существующие в Сизифе полиси. Участники: Андрей Орлов, Михаил 
Забалуев и я.



----- Begin Forwarded messages -----

MZ> Про то, что нужно сделать книжку в DocBook и включить ее в alt-docs,
MZ> говорю уже не только я. Поймите меня правильно, дело вовсе не в
MZ> спортивной правоте.
 
AO> Ну так займитесь. Исходники документации открыты. Поймите меня правильно -
AO> дело вовсе не в спортивной 
AO> правоте, работа по поддержке пакетов дело сугубо добровольное и я
AO> действительно не имею возможности
AO> поддерживать доку в докбук. Я один раз попробовал - на документации к Zope - и
AO> в общем-то этого напряга не выдержал.
AO> В том числе и потому, что самый частый вопрос, который я видел у себя в
AO> почтовом ящике - чем эту "???;%" прочитать и нельзя ли
AO> ее у меня получить в виде текста.

KM> Андрей, я предлагаю Вам включить и поддерживать в alt-docs@ Вашу документацию
KM> в том формате, который Вас устраивает, как я понимаю, это ST.
 
KM> В docs@ уже был разговор о том, что нужно организовать репозиторий ``исходных
KM> текстов'' документации, в котором авторы могли бы поддерживать свои тексты
KM> в актуальном состоянии в любом удобном им формате. Преобразование текстов
KM> этого репозитория в DocBook, редактура, подготовка книжек и пакетов, а также
KM> отслеживание изменений, сделанных авторами _в этом репозитории_ -- это,
KM> собственно, уже задачи участников проекта DOCS.


KM> Надеюсь что Вам, как автору, будет несложно обновлять свою документацию ещё в одном месте (это можно даже автоматизировать). 


AO> Чего уж проще: rpm -Uvh rpm-build-python;  cvs commit; 
AO> :)

KM> Нам будет гораздо проще в этом случае отследить изменения и вовремя обновить документацию, чем следить за обновлением 
KM> каждого продукта и сопровождающих его текстов.   

AO> Хорошо. Как я уже писал - в принципе я согласен.

KM> Предложения и замечания по организации ``репозитория исходных текстов KM> документации'' необходимы и будут очень кстати в рассылке docs at . 

AO> Я пока предложений высказывать не буду, хочу только получить ответы на неск. вопросов, часть из которых навеяна прошлым опытом:
 
AO> 1. Если у нас уже какая-либо практика ведения в док буке именно ПОЛИСИ на пакетирование? Вопрос задан потому,
AO> что есть несколько характерных особенностей, которые я заметил по крайней мере на своей практике, и мне бы хотелось понять,
AO> как это будет решаться.

KM> Пока единственное полиси в докбуке -- alt-packaging, которое я обновил
KM> по новой версии текста от Димы Левина перед выходом ALM 2.4.
KM> Так что нет практики. Поскольку сборник полиси по проекту Sisyphus всё
KM> равно нужен, такую практику придётся создавать.


AO> 2. Будут ли документы полиси опубликованы где-л. в общедоступном месте? Особенност вопроса в том, что многие документы
AO> постоянно обновляются, и их обновление должно незамедлительно публиковаться. На тьекущий момент - все доки сбраны в одном месте,
AO> в пакете rpm-build-python - все решается просто. Если в инет будет выкладыватся версия полугодовой давности - вреда будет больше чем пользы.
AO> Вопрос даже не в том, что информация может перестать быть валидной - это для полиси не характерно - вопрос в том, что полиси не содержащая
AO> последние (наиболее актуальные) изменения будет создавать потребителю ложную видимость знакомства с полиси.

KM> Все документы из пакетов alt-docs-* скоро таки будут опубликованы на сайте
KM> docs.altlinux.ru, и там будут всегда последние версии. Сейчас последние
KM> версии документов представлены в Сизифе в пакетах alt-docs-*.

KM> Если удастся хорошо организовать систему обновлений документации, так что
KM> участники проекта docs сразу и непосредственно будут узнавать о выходе новой
KM> версии полиси, то обновление текста в DocBook и выкладывание в сеть -- дело
KM> техники. Перечисленные выше причины, пожалуй, свидетельствуют за то, чтобы
KM> объявить обновление полиси (т. е. пакета alt-docs-devel) приоритетной задачей.
KM> Это будет оправданно, если этот пакет действительно будет востребован, как
KM> отражающий текущее состояние разработки в Сизифе: как справочник для опытных
KM> и руководство для начинающих. Пока мне кажется, что так и должно произойти.


AO> 3. Как будут решаться вопросы с литературной правкой? Чгря даже на случае с Zope у меня были некоторые проблемы, а то была все-таки
AO> более менее старательно написанная документация, тогда как в случае с полиси литературность я однозначно приношу в жертву оперативности
AO> обновления и однозначности текста. 

KM> Для литературной правки есть отличный момент перехода текста из авторского
KM> варианта в DocBook. Можно и нужно делать не только разметку текста, но и
KM> редактуру (так, впрочем, почти всегда и происходит). Серьёзная проблема,
KM> которой я пока не могу предложить никакого практического решения -- как потом
KM> обратно вносить редактуру в авторский текст? Если сразу править именно исходный
KM> вариант, предоставленный автором, то всё равно потом придётся дублировать
KM> изменения в DocBook. Но, конечно, и автору нет смысла пренебрегать чаще
KM> полезной, чем вредной литературной и прочей правкой.


AO> 4. Python-полиси содержит явные и неявные ссылки на другую аналогичную документацию, в частности из пакета rpm/rpm-build. Будет ли
AO> эта документация поддерживаться там же (может быть, уже поддерживается)?

KM> Честно говоря, лучше все неявные ссылки сделать явными.
KM> Уверен, что это во всех случаях возможно и в подавляющем большинстве --
KM> полезно.

KM> README.ALT из rpm -- интегрирована с alt-packaging в том же пакете
KM> alt-docs-devel (там тексты несколько пересекались). Раз уж оно туда
KM> попало, то поддерживаться будет. Если получится схема поддержки
KM> полиси, rpm policy тоже будет поддерживаться по этой схеме.
KM> Про документацию из rpm-build я просто не знаю -- вопрос к Вам и к авторам:
KM> что из этого имеет отношение к Сизифу и нужно в alt-docs-devel?
KM> Будем включать.

AO> 5. Как будет решаться вопрос с версиями, а самое главное - с паралельными ветвями полиси? Сейчас версия полиси лежит в пакете rpm-build-python
AO> и возможность установки и использования этого пакета примерно совпадает с границами применимости полиси, это, может быть, не совсем
AO> удобно, зато  управляемо, объяснимо и воспроизводимо.

AO> В любом случае, я прошу, до тех пор, пока эта технология не будет обкатана, что бы на видном месте 
AO> стояло следующие замечание: "это неофициальная версия полиси, которая, возможно, искажена или устарела. 
AO> Официальная версия содержится в пакете rpm-build-python"

KM> А если в начале каждого полиси, опубликованного в alt-docs-devel, поставить
KM> +обязательную краткую справку: к какой версии соответствующего продукта этот
KM> текст относится, какой он имеет статус (пробный, предложение, обязательный
KM> и общепринятый, устаревающий и т. п.), и также _какие ещё_ версии существуют
KM> наряду с ним, _где_ и _с каким статусом_).
 
KM> Поскольку это один абзац в начале текста, при смене позиций (например, смене
KM> статуса текущего опубликованного документа с общепринятого на устаревший
KM> и под.) -- обновление его в online-версии alt-docs-devel можно сделать
KM> _очень оперативно_. Это не предполагает, что нужно сразу разметить в
KM> DocBook и опубликовать новую версию полиси, на что нужно время. Нужно только,
KM> чтобы автор позаботился об обновлении одного абзаца о статусе текста.
 
KM> Мне такой вариант представляется гораздо более информативным, чем оговорка
KM> о возможной (но необязательной) неадекватности документа. Более того, он
KM> позволяет предавать гласности спорные предложения, не дожидаясь единогласия
KM> (которое может и не наступить) и при этом никого не вводя в заблуждение
KM> относительно их статуса: просто нужно оговорить, что перед читателем --
KM> предложение. Разработка, в конце концов, это поиск, и документация
KM> должна это отражать.

KM> При всем alt-docs-devel я готов в начале поставить объяснение его статуса:
KM> отражает текущее состояние разработки, поэтому если Вы хотите знать наверняка --
KM> не полагаётесь на печатную версию или пакет в дистрибутиве, смотрите последнюю
KM> версию в Сизифе или на сайте.

----- End forwarded messages -----

-- 
Kirill Maslinsky
ALT Linux Team * Documentation Project