[docs] документация, инфраструктура, фирмы, сообщество

[Alexandre Prokoudine]

Michael Shigorin пишет:

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

Хм, у сотрудников альта 8-часовой рабочий день? Новость, достойная LOR.

  > И ещё одно.  Не надо писать про то, в какую позу надо встать
> с какой железкой, чтобы она завелась.  Надо честно писать --
> "ОФИЦИАЛЬНО НЕ ПОДДЕРЖИВАЕТСЯ", сделав где-то общую ремарку про
> то, что именно это значит: "с минимально необходимыми усилиями,
> обусловленными технической невозможностью автоматизации".

Разумно. Однако...

> Потому как это не редактора надо автоматизировать, чтоб писанину
> про то, как WinCE'шную штуковину или там GPRS под местным
> линуксом прикрутить, а сперва сделать всё, что можно, для
> "воткнул-заработало", а потом уже смотреть, осталось что-то
> автоматизировать или остался список рекомендуемых программ.

Краткий ответ
-------------

При нынешних возможностях ALT, если я правильно их оцениваю, путешествие 
по твоему пути ограничивает решения на основе дистрибутивов ALT Linux 
серверами, маршрутизаторами и прочей сетевой фигнёй. А свободный десктоп 
сладко сосёт лапу в берлоге, видя сны об охоте на Длиннорогого.

Длинный ответ
-------------

В твоём письме я увидел три темы:

1. Перенос активной разработки в wiki, как более совершенную 
инфраструктуру коллективной работы.

2. Перенос специфики as of now решений в онлайн с оставлением в печати 
чего-то "устойчивого и неизменного".

3. Отказ от документирования "костылей". Тема, сильно пересекающаяся со 
второй.

А вот теперь я начну медленно и печально огорчать тебя. По пунктам.

1. "Перенос активной разработки в wiki..."

Wiki как технология само по себе не спасает. Нужна жёстко 
командно-ориентированная работа с хорошим менеджементом.

Мотивирую. Ну выложил я свои доки по работе со звуком в ру.викибукс.орг. 
Дальше что? Появились два постоянных коммиттера, которые готовы работать 
и дальше при наличии чётко указанного направления, плюс несколько 
анонимных фиксильщиков багов, которые пару раз прошлись по тексту и 
исправили очепятки. С 25 апреля никаких правок в тексте не было и 
объяснение тому наипростейшее: командная работа подразумевает наличие 
лидера, т.е. некоей направляющей силы. А я заранее сообщил, что буду 
заниматься книжкой весьма нерегулярно. Итого: светлое будущее у этой 
доки будет видно только в том случае, если работа будет хорошо 
организована, а обязанности строго распределены.

Делай выводы.

2. "Перенос специфики as of now решений в онлайн..."

В твоём письме прозвучал туманный намёк на то, что нужно документировать 
нечто очень стабильное, нечасто изменяющееся/изменяемое и потому могущее 
пригодиться для курсов и даже издателей.

Раскрою тебе "страшную тайну": выпускать книжки по прикладухе к 
GNU/Linux невыгодно. Шанс стать читаемой и популярной есть только у 
электронной документации, качественной и поддерживаемой.

Мотивирую.

Выпустивший книжку по Adobe InDesign CS может быть уверен, что следующая 
версия продукта выйдет в лучшем случае через год-полтора, а значит тираж 
разойдётся, а то и будет повторно выпущен.

Выпустивший книжку по Scribus -- самоубийца. Выпустивший книжку по 
Inkscape -- самоубийца, склонный к особо садистским извращениям над 
читателями. Когда в продукте от версии к версии прибавляется увесистая 
пачка новшеств, пересмотр и обновление документации становится весьма 
нетривиальной задачей, которую приходится выполнять раз в 3-6 месяцев - 
к каждому релизу.

Почитай внимательно http://lrn.ru/~avp/docs/linuxprepress.htm, особенно 
главу "Управление цветом". Лично я предвижу решение части описанных 
проблем в течении полугода-года. А теперь представь себе, что только что 
выпущена книжка, где всё построено на текущем положении дел. Издатели, 
если ты вдруг совершенно случайно не в курсе, не такие идиоты, чтобы 
вкладывать деньги в публикацию материала, который через год никем 
покупаться не будет по причине близкого к полному морального устаревания 
текста.

Между прочим, это экстраполируется на офигительно большое количество 
тем, притом не только мультимедийных.

Делай выводы.

3. Отказ от документирования "костылей".

Если рассуждать с твоей позиции, то, к примеру, художники должны забыть 
про GNU/Linux только потому, что

а) драйверов linuxwacom в альте нет;
б) даже если появятся, то после их установки нужно руками подправить 
/etc/X11/xorg.conf и /etc/modprobe.conf (или что там сейчас в альте_;
в) в GIMP открыть палитру "Статус устройства" и для каждого из устройств 
  Cursor, Pen и Eraser указать свой гимповый инструмент (и схожие 
действия для Krita);
г) а в фотошопе под виндой/макосью пункты а)-в)  делать не надо.

Срок жизни такой документации может быть очень разным.

1) Wacom-HOWTO как направление документирования (а не конкретный 
документ) существует уже года четыре, а то и все пять. При этом меняется 
лишь описание решения, а  нормального решения задачи по настройке 
планшетки нет и пока что-то не ожидается (ау, поклонники udev и HAL!).

2) В то же самое время приличная часть Cyrillic-HOWTO -- другого 
сборника "костылей" -- сильно устарела.

Итого: предсказать скорость устаревания документации по "костылям" 
практически невозможно.

Делай выводы.

С пунктами разобрались. Поехали дальше.

Дружно вспоминаем о пресловутой документации, описывающей решение 
типовых задач. Она подразумевает изложения материала на двух уровнях:

а) теория aka "почему и благодаря чему оно работает так";
б) практика aka "каков оптимальный способ способ сделать это".

Вопреки расхожему мнению, теоретическая часть всё-таки ЗАВИСИТ от 
_практической_ реализации, которая в свою очередь зависит от теоретической.

Объясняю. Можно сколь угодно упорно учить пользователей теории и 
практике цветокоррекции при помощи имеющейся версии The GIMP. Как только 
в Гимп добавляют цмиковые каналы, вся эта документация, как в 
теоретической, так и в практической её части идёт лесом под напором 
юзеров, начитавшихся Маргулиса. Ты лично ничего не можешь с этим 
поделать. И ничья опенсорсная харизма с этим ничего не сделает. Потому 
что, IIRC, годовой тираж одной-единственной книжки Маргулиса превышает 
количество заходов на gimp.ru за год в целом. Ситуация меняется, но путь 
эволюции долог и полон тупиковых ветвей видов.

Сухой остаток. Если ты считаешь, что документирование костылей и 
специфики текущих версий софта должно переместиться в wiki, а на бумаге 
должна остаться теория и основы практики, предлагаю тебе выставить на 
обсуждение твою версию содержания "Руководства пользователя".

А.П.