Как жаль, что очень многие сейчас забыли про проект LinuxGazette, а ведь он живет и здравствует по сей день.
Как жаль что очень многие современные разработчики в сфере FOSS не читали статью от туда:
И не знают про цикл статей “Writing Documentation” в этой самой LinuxGazette:
- Writing Documentation - Part 1: POD
- Writing Documentation, Part II: LaTeX with latex2html
- Writing Documentation, Part III: DocBook/XML
- Writing Documentation, Part IV: Texinfo
В частности, POD оказался достаточно простым и ненакладным способом писать документации в виде страниц руководств (man-pages).
Люди, разработчики, программисты! Пишите документацию! Хорошая документация очень привлекает внимание к проекту, помогает разобраться в нем, легче написать какие-то модификации, патчи и, в конечном итоге, помочь ему и вам.
Примеры отвратительного документирования? Да пожалуй почти все творения FreeDesktop.org (по моему мнению, так их деятельность, это диверсия в рядах FOSS), к примеру HAL, для которого сначала написали реализацию, и, по-моему, до сих пор не существует спецификации, как результат - им показалось что HAL тяжел, разделили его на отдельные демоны-сервисы, а кто был завязан на него получили головную боль (особенно кто пользовался монтированием флешек/дисков, или тот же Xorg, которому пришлось придумывать свою систему для настроек подключенных на горячую устройств ввода).
Или xdg-utils… посмотрите man xdg-open (навеяно дискуссией в #archlinux-ru@FreeNode), вроде и есть, ну никакой ясности не вносит - кто, что будет открывать, какие браузеры или переменные окружения будут использоваться, какие окружения рабочего стола поддерживаются.
Ну и последнее, вы что нибудь можете сказать о загадочной утилите ck-launch-session из комплекта PolKit? Нет? Да она даже на –help или -h подсказки не выдает, кто она и что делает. А ведь применяется много кем, кто не использует gdm/kdm/etcdm, в знакомой мантре в .xinitrc: exec ck-launch-session startkde