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

Ср Май 11 15:39:39 MSD 2005

On Wed, May 11, 2005 at 09:28:56AM +0400, Kirill Maslinsky wrote:
> > разделить _публикацию_ документации, пишущейся в процессе
> > использования, в _онлайне_ (это wiki и никаких костылей
> > велосипедных с доступом по rsync/ssh тут изобретать не надо)
> > 
> > и _поддерживаемую_ документацию вести отдельным бранчем в таки
> > да, чём-то single-source (пуркуа бы и не DB/XML, при всей моей
> > нежной любви к последнему из них),
> > 
> > дабы в итоге получить приемлемую для решения повседневных
> > вопросов (по соотношению точность/актуальность) онлайновую
> > документацию, начиная с wiki.sisyphus.ru, и небольшую, но
> > достойную печатную.
> Честно говоря, я так и не понял, в чём конструктивная суть
> этого предложения.

Как мог -- так написал, объяснить лучше вряд ли выйдет.

Сопоставляя динамику различных авторов на heap.altlinux.ru и
wiki.sisyphus.ru, вывод про (затёрто) в общем, неадекватность
модели первого из них _для меня_ так же очевиден, как и
изначальное предположение о такой судьбе этого механизма --
кривое сочетание строгости (точности) по доступу и
характеризации и типа вольной формы самого контента,
вплоть до неявности этой самой формы.

Обдумывая цели (и возможности) сообщества и фирм, написал то,
что написал.  Для фирм в процессе подготовки документации важно:

- single-source электронного и бумажного вариантов;
  + скорее всего -- довёрстка печатного варианта;
- профилирование (руководства, книги, курсы; уровни);
- вычитанность и вылизанность.

Соответственно подобный incoming с гипотетическими конверторами
так и оставил висеть в воздухе задачу синхронизации, зато создал
ряд новых относительно тех самых wiki, что позор ввиду времени
существования последних как технологии.  Ну да ладно.

> Пожалуй, главный вопрос из тех, которые возникают: а каким
> именно образом wiki-публикация будет превращаться в
> поддерживаемую документацию (или никаким и подразумевается,
> что это две не связанные вещи)? 

Подразумевается, что из несколько структурированного и, возможно,
корректно изложенного технически материала на wiki может
получиться статья или фрагмент официальной документации.

Это процесс технико-литературного редактирования, который всецело
полагается на сотрудников компании и лишь по везению, на которое
нельзя рассчитывать -- на волонтеров, начиная с (со)авторов
оригинального текста.

Т.е. я отказываюсь от мысли, что волонтеры будут предоставлять
материал в практически готовом к публикации виде -- ещё раз
повторюсь, одно такое сообщество здесь умудрились собрать и
развалить (Кирилл, это не к Вам претензия, а к AEN и Rider,
которые так ничего и не поняли из того, что именно avp@ за те
копейки здесь сделал и сколько на этом можно было заработать,
если видеть дальше носа и уметь не только требовать на вчера
по невнятному ТЗ с вечноплывущими сроками).

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

Вот и написал, что думаю.  Как есть.

> Мысли по теме: Безусловно, в wiki появляется масса информации,
> которая нужна в документации. Хочется поместить эту информацию
> в документацию, в первую очередь в оффлайновую html, потом м.
> б. ещё и в печатную, делая при этом минимум лишней и
> дублирующей работы.

Скорее наоборот -- танцуя от _дистрибутивов_ и _печатной_.
Потому как wiki -- уже онлайновая.

> Но просто взять и поместить текст из wiki в документацию тоже
> не очень можно, в силу другого уровня требований к тексту (хотя
> бы по языку/орфографии, не говоря уже о структурированной
> подаче информации).

Вообще нельзя.  По умолчанию лучше исходить, что это rewrite и
copy-paste поддаются только фрагменты кода/конфигурации (btw,
есть мнение, что последние не должны бывать больше половины
печатной страницы _вообще_, но это отдельная история).

> Хорошого решения интеграции wiki и документации мне пока
> придумать не удалось. Есть ли конструктивные (и конкретные)
> предложения?

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

Мартовскую тему про оглавление читал очень диагонально и первые
пару писем, но посоветовал исходить бы не из того, что туда
МОЖНО (в принципе, при неограниченном времени и возможностях
тестирования описанного в документации) напихать, про PDA там
всякие, а из того, что или уже есть и известно (спросить в
community@) как работающее, или 100% пишется своими силами
с привлечением существующих материалов.

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

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

Иначе docs@ будет заменять разработку, при этом никакие усилия
и кости здесь не будут исправлять клинические ситуации там.

А так -- будет смысл читать (и покупать) такую документацию,
которой мало (это же хорошо!), но каждое слово на своём месте.
Будет смысл кооперироваться с курсами, издателями самостоятельных
книг.

Очень много смысла давно здесь продумано, вот только для этого
нельзя замыкаться на самих себя и делать дурную работу просто
ради "сделано здеся".

Уметь надо с коллегами работать.

-- 
 ---- WBR, Michael Shigorin <mike на altlinux.ru>
  ------ Linux.Kiev http://www.linux.kiev.ua/
----------- следущая часть -----------
Было удалено вложение не в текстовом формате...
Имя     : отсутствует
Тип     : application/pgp-signature
Размер  : 189 байтов
Описание: отсутствует
Url     : http://lists.altlinux.ru/pipermail/docs/attachments/20050511/3cb18a86/attachment.bin