Re: [devel] ALT packaging docs (was: О сборке программ на GTK / GNOME)

[Kirill Maslinsky <kirill@altlinux.ru>]

Доброе, уже, наверное, утро.


> > Надеюсь что Вам, как автору, будет несложно обновлять свою документацию ещё в одном месте (это можно даже автоматизировать).
> 
> Чего уж проще: rpm -Uvh rpm-build-python;  cvs commit; 
> :)

Этот разговор я хотел бы продолжить в docs@, куда и направляю копию, 
но если кто-то из тех подписчиков devel@, кто не читает docs@, 
захочет что-нибудь добавить или откомментировать, пожалуйста, 
не стесняйтесь это делать и здесь. 

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

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

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

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

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

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

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

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

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

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

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

А если в начале каждого полиси, опубликованного в alt-docs-devel, поставить обязательную краткую справку: к какой версии соответствующего продукта этот 
текст относится, какой он имеет статус (пробный, предложение, обязательный
и общепринятый, устаревающий и т. п.), и также _какие ещё_ версии существуют
наряду с ним, _где_ и _с каким статусом_). 

Поскольку это один абзац в начале текста, при смене позиций (например, смене
статуса текущего опубликованного документа с общепринятого на устаревший 
и под.) -- обновление его в online-версии alt-docs-devel можно сделать 
_очень оперативно_. Это не предполагает, что нужно сразу разметить в 
DocBook и опубликовать новую версию полиси, на что нужно время. Нужно только,
чтобы автор позаботился об обновлении одного абзаца о статусе текста. 

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

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

-- 
Kirill Maslinsky
ALT Linux Team * Documentation Project