[devel] кому нужна документация в эпоху интернета

[Alexey V. Vissarionov]

On 2020-11-20 04:59:33 +0300, Leonid Krivoshein wrote:

 >>> Может быть, я немного утрирую, но лишь совсем немного.
 >> вопрос в нужности этой документации. т.е. - если бы ей кто-то
 >> пользовался, то да, конечно надо паковать.
 > Есть люди, которые ей пользуются. И вариант, что "мы это описали
 > на ВиКи" не катит. Жаль, таких людей очень мало.

Среди пользователей - да (они в массе своей документацию вообще не
читают, пока все не сломают). А среди админов TFM очень ценятся, а
умение их R - тем более.

 >> а если ей никто не пользуется - то зачем ?
 > Если пользуется не много людей, в инсталляторе должен быть
 > флажок "Документация" (он у нас есть, но про другое) в
 > изначально очищенном состоянии.

И, соответственно, с правильно настроенными зависимостями: %name
может быть пустым и требовать %name-bin и %name-man, но эти два
подпакета должны ставиться независимо. Не говоря уж о том, что
%name-man обязан быть noarch - мы ведь не хотим запрещать читать
мануал по какому-нибудь U-boot на писюшатине, ага?

 > А пакеты с документацией в репозитории и на установочном диске
 > нужны, ставить их или нет -- решает админ, паковать в тот же
 > пакет или в *-doc -- меинтейнер,

Админу удобнее, когда пакет нарезан достаточно мелко - чтобы можно
было, например, ставить не %name со всем, что оно за собой потянет,
а, например, на один компутер %name-libs + %name-tool + %name-man,
на другой %name-man и %name-doc (на сервер и на админский ноутбук
соответственно, если кому-то неочевидно).

Но и про малоквалифицированных пользователей забывать нельзя: %name
должен тянуть за собой какой-то разумный набор наподобие %name-libs
+ %name-tool + %name-man + %name-scripts + %name-config, но без doc
и devel.

А пихать %doc в основной пакет лучше не надо: людей ничего так не
раздражает, как попытки думать и принимать решения за них. Даже тех,
кто знает про --excludedocs (потому что документация бывает нужна
сама по себе).

 > в случае библиотек/API это разумно отделять, я считаю.

Разумеется: отдельно %name-libs, отдельно %name-devel-libs-shared и
%name-devel-libs-static (оба подпакета Provides: %name-devel-libs),
отдельно %name-devel (*.h, *.pc, Requires: %name-devel-libs), и уж
тем более отдельно %name-devel-man и %name-devel-doc (которые точно
будут ставиться не в сборочную среду, а на рабочую станцию человека,
ведущего разработку).

Но увы: пока что мейнтейнеры предпочитают придерживаться ГОСТ 8486-86
и ГОСТ 26074-84 (разумеется, одновременно). А когда кто-то пытается
объяснить им, что можно сделать лучше - смотрят телячьими глазами:
"а зачем? и так все работает".


-- 
Alexey V. Vissarionov
gremlin ПРИ altlinux ТЧК org; +vii-cmiii-ccxxix-lxxix-xlii
GPG: 0D92F19E1C0DC36E27F61A29CD17E2B43D879005 @ hkp://keys.gnupg.net