[docs] о проектах (was: M24 docs impressions)

[Michael Shigorin]

On Wed, Dec 08, 2004 at 12:51:29AM +0300, Kirill Maslinsky wrote:
> Ну ладно, неустройство так неустройство.

Да не ладно, будем лечить.

> Некоторое время назад я спрашивал здесь в рассылке о
> каком-нибудь тексте о том, что такое проект docs, его задачи и
> т. п. Выснилось, что такого текста нет.

А можно, расскажу, как он начинался?

Был такой Master 2.0 и его документация, которая, похоже,
писалась всем альтовским офисом в OOWriter, а потом вычитывалась
в режиме "пинг-понг" Сашей Прокудиным, Андреем Астафьевым и
покорным слугой.  В результате возникло ощущение, что для данного
вида collaboration лучше бы рассылку, да и трёхмегабайтные
труднодиффуемые "подарки" по дайлапу были тем ещё счастьем
(=> репозиторий и другой формат, что решало и проблему с
монолитностью при правильном подборе оного; да и с качеством
результата, но лично меня тогда это беспокоило не в первую
очередь).

Далее возникло устойчивое понимание того, что хорошая
документация -- это не вода, а наоборот -- очень плотная
информация, сжатая, которая _не_ включает пространные листинги
конфигов (которые надо класть в электронную документацию пакетов
и ссылаться на них), которая имеет краткое введение в предметную
область (например, для apache -- что это такое, где читать про
HTTP, что такое виртуальные хосты -- и, пожалуй, "в детали).

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

Которая имеет некий roadmap, несмотря на то, что склеена из
разных кусочков (не стоит бояться сказать об этом сразу) -- см.
введение в "Programming Ruby" из ruby-doc-extra, там весьма
хорошо сформулировано: "если... то читайте, если... то, ну а если
i-dont-need-no-stinkin-docs -- то неплохая стильная подставка под
кофе". :)

> Честно говоря, похоже, что нет и чёткого (и единого!) мнения у
> участников, где проект docs начинается, где кончается, что
> сделано в его рамках, а что уже нет.

Что значит "уже нет"?  Это некорректная постановка вопроса! :)

> Поэтому в книжках ничего нет о проекте -- непонятно, что
> писать. Есть тексты документации, есть их авторы -- это
> понятно. 

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

Общий смысл моего понимания того, как подобный проект может быть
устойчиво жизнеспособным и полезным для всех своих участников
(а также широкого круга пользователей) -- это именно то, что люди
делают вещи для себя тем образом, который им скорее удобен, при
этом не боясь по ходу дела учиться и набираться опыта от коллег
по команде; а вот фирма фокусируется на том, что нужно ей --
обеспечении гарантированного качества некоторого подмножества
результатов для того, чтобы снизить себестоимость поддержки
создаваемых и поставляемых ею решений.  Не пытаясь перевалить
бремя поддержания этого качества на волонтеров, btw.

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

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

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

> Действительно важная проблема: оценка адекватности текстов.

Expires: ?

> Вышеперечисленные вопросы, на мой взгляд, по крайней мере
> отчасти связаны с тем, что круг обязанностей участника проекта
> docs совсем не определён.

А не хотите написать "введение в docs" -- документ на манер
maintainer's howto?  Буду рад помочь соображениями, если они
будут признаны полезными и реализуемыми.

> Поэтому, написав в docs@, никогда точно не знаешь, каков будет
> результат и будет ли вообще.  Позволю себе сравнить ситуацию с
> devel на . Есть круг обязанностей мантейнера (есть соответствующий
> документ).  Если пакет перестал собираться -- письмо мантейнеру
> и в devel на . Всё ясно.

Ну, всё сложнее, но bugzilla у docs тоже есть. :)

> Обязанности же автора по отношению к документу... Должен ли
> автор что-то сделать, если документ устарел и перестал
> соответствовать реальности?  Схема orphaned/obsolete здесь не
> лишена смысла.

Да.  Только критерии чуть другие.

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

Вышеуказанные пойдут в качестве дополнения ("более ранней
стадии") к вашему с cray@ обсуждению?

> > Из мелкого занудства:
> Позвольте на мелкое занудство ответить мелким занудством ;)

Позвольте, в свою очередь, тоже понудеть :-))

> > В руководстве по установке есть глава "Что такое ALT Linux" с 
> > описанием ALT Linux Team и Сизифа. При этом есть отдельная
> > книга "ALT Linux Team и проект Sisyphus".
> Не вижу противоречия.

А у меня тоже возникло дежавю при прочтении.  Этого не должно
быть, как это ни смешно. :)

> У раздела и у книжки -- совсем разные задачи, содержание, и,
> возможно, даже аудитория (может, и не всякий полезет в "ALT
> Linux Team", кто полезет в руководство по установке).  Так что
> пусть.

Э, не: не всякий полезет и в sisyphus на .  По крайней мере если
непонимание вышеизложенного не скатит результаты проекта к тому,
что решения заказчикам будут лепиться прямо из Sisyphus,
ликвидировав понятие поддерживаемой платформы как таковое.

Впрочем, тогда народ просто разбежится на SuSE, Fedora и Debian,
что и наблюдаем в заметной мере уже сейчас.

PS: извиняюсь, если кому чего разбередил, но или говорить, или
молчать в тряпочку.  Тряпочки рядом не оказалось. :]

-- 
 ---- 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/20041208/8eac33cb/attachment.bin