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

[Michael Shigorin]

On Wed, May 11, 2005 at 06:46:08PM +0400, Alexandre Prokoudine wrote:
> А вот теперь я начну медленно и печально огорчать тебя. По пунктам.

Не выйдет :-)  Саш, спасибо, но это всё старые новости.

И про восемь часов, как ты мог догадаться, сказано не случайно.
_Рассчитывать_ надо только на это, иначе на творчество сил не
останется.  А человек -- не машина, без этой отдушины мрёт.

> 1. "Перенос активной разработки в wiki..."
> Wiki как технология само по себе не спасает. Нужна жёстко 
> командно-ориентированная работа с хорошим менеджементом.

Ессно.  Плюс в зависимости от движка и настроек риски потери
материала или вандализма в дополнение к обычным.

Это всё понятно.

При всём при этом моей реакцией на последние домогания heapbot'а
было "rsync --delete /var/empty/ incoming:...", а вот на
вываливание Антоном доки по Separator -- пойти и докинуть того,
что тут накопали.

Ну и сейчас вот думаю -- получится ли отвлечь Кирилла на то,
чтобы посмотреть, чего там на этих самых wiki.sisyphus.ru и
freesource.info/wiki/AltLinux (предшественник) накопилось и 
где хорошей информации не хватает структуры (не контенту
страничек, а самим страничкам), или нет.

> 2. "Перенос специфики as of now решений в онлайн..."
> В твоём письме прозвучал туманный намёк на то, что нужно
> документировать нечто очень стабильное, нечасто изменяющееся/
> изменяемое и потому могущее пригодиться для курсов и даже
> издателей.

Попробую переформулировать словами cray@: "есть такой опыт, что
при разработке надо жить на бетах, чтобы к выходу твоего продукта
именно они были стабильным и поддерживаемым текущим выпуском".

Здесь туманный намёк мог быть разве на то, что "текущую"
документацию по Sisyphus и последнему stable (их нюансам и просто
граблям) и надо ревизировать по мере подготовки какого-либо
выпуска чего бы то ни было, к чему эти описания могут иметь
отношение.  Подумал и решил не усложнять было этим изложение,
поскольку это чуточку ортогонально.

Re курсы -- пооткровенничаю и я: эти мысли зреют уже пару лет,
с тех пор как взял и стал читать (а потом с pilot@ -- и писать)
квазаровские курсы на базе Master 2.0/2.2.

Ряд грабель ALM, кстати, очень познавательно раскрывается именно
на курсах, всем интересно было.  Даже мне. :-)

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

Спасибо, мне уже доложили -- начиная с толстых пошаговых книжек
по шестому редхату на Петровке.

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

Да нет.  Просто для такого есть google, faq, wiki, hardware на .

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

Ессно.  Я ж и предлагаю не пытаться фиксировать такое в бумагу,
цинично убивая время на подготовку и деревья с вторсырьём.

Мало того, вот тут сестрёнка готовила поездку в... в общем,
неважно куда, но нюансов там хватает.  Добыли соответствующий том
The Lonely Planet, вытянули и распечатали к нему Upgrade, который
и уточнял, что курсы уехали так-то, ситуация с гостиницами --
так-то, ну и плюс свежие отчёты недавно съездивших доверенных.

Это БУМАЖНЫЙ бизнес, просто ландшафт тоже чуточку быстрее
меняется, чем переиздания.  И без online upgrades цена этой
бумаге заметно меньшая, думаю, это там тоже учтено.

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

Местами можно, у меня при прочтении разных HOWTO порой
складывались разные ощущения именно на тему "как это будет
применимо".  Скажем, Partition и Multi-Disk и посейчас в top10
моих рекомендаций.  Усекаешь?

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

Ну поехали, но пока вынужден тебя огорчить -- ты подпеваешь :-)

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

Именно.

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

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

> а на бумаге должна остаться теория и основы практики, предлагаю
> тебе выставить на обсуждение твою версию содержания
> "Руководства пользователя".

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

Бишь вместо ковыряния стен начинаю ковырять фундамент, что тоже
надо, но ведь и его /под стены/ тоже надо планировать.

-- 
 ---- WBR, Michael Shigorin <mike на altlinux.ru>
  ------ Linux.Kiev http://www.linux.kiev.ua/