[docs] Re: mozilla.ru

[Vadim Vinichenko]

Maksim Otstavnov пишет:
> Hello Vadim,
> 
> Monday, March 17, 2003, 8:41:36 PM, you wrote:
> 
> VV> Традиционный подход к документированию "программных продуктов" часто
> VV> выглядит примерно следующим образом. Составляется одно из двух или оба 
> VV> вместе:
> 
> VV> * User Guide, написанный в (как правило, фантастическом) предположении, 
> VV> что пользователь, последовательно читает его, сидя перед программой и 
> VV> последовательно овладевая ее функциями, от простейших до самых сложных;
> 
> А почему "фантастическом"?

На основе личного опыта. Опыт других может отличаться.

> VV> * Reference Manual, справочник, претендующий на всеохватность и 
> VV> освещающий в равной степени вещи очевидные и тривиальные и совсем 
> VV> нетривиальные.
> 
> VV> Если дойдут руки, к этому может быть приложен Quick Starter Guide, а уж 
> VV> когда отстрелялись по этим мишеням, можно добавлять всякие "Приемы 
> VV> эффективного использования..." и т.п.,
> 
> Еще учебник бывает. Это несколько отличный от гайда стиль.
> 
> VV> до которых руки, как правило, не доходят, а умник еще и скажет,
> VV> что это такая "экосистема" в отрасли - "Приемы..." оставлены
> VV> независимым авторам (или отдельному корпоративному
> VV> издательству:-).
> 
> VV> Сей канон нам заклеймить нетрудно:-) - большинство информации никогда не 
> VV> бывает востребовано и "загораживает" доступ к информации действительно 
> VV> нужной.
> 
> Непонятно, зачем клеймить, и неочевидна истинность второго члена.

Дело в том, что это написано в контексте обсуждения "монументальных" 
руководств к "тяжелым" гуевым программам и средам (GNOME, KDE, Mozilla). 
У меня нет сомнения в том, что Library Reference к ЯП должна содержать 
описание всех функций, даже если любой отдельно взятый пользователь 90% 
из них никогда использовать не будет, и они "загораживают" ему полезные 
10%. Однако похоже, что применение сходных принципов к документированию 
гуевых программ для пользователя рождает бесконечные тавтологичные 
мантры типа "Нажмите на кнопку <Сделать папкой новых закладок по 
умолчанию>, чтобы сделать выбранную папку пакой новых закладок по 
умолчанию" или описания на три страницы какого-нибудь Wizard'a, в 
окошках которого все уже и так разжевано до неприличия.

Есть подозрение, что для таких программ нужен некий agile documenting, 
облегченный подход к документированию, исходящий из того, что GUI в 
значительной степени самодокументирован. Вероятно, в большинстве случаев 
достаточно, отталкиваясь от тех или иных задач, направить пользователя 
за определенной группой настроек или выполнением определенных действий в 
надлежащее меню/диалог, а с большинством конкретных действий он 
разберется сам. Разумеется, должны быть сделаны необходимые 
предупреждения, оговорены моменты "потенциально неочевидного" поведения. 
Из двадцати полей Wizard'a поименно отметить те два, смысл которых, 
возможно, неочевиден. Но все же - не педантичное поштучное описание 
кнопок и флажков.

> VV> И соблюдать каноны мы здесь никому не должны.
> 
> Кто говорил в модальности долженствования?

Да никто не говорил. Это просто фрагмент моей внутренней полемики 
прорывается, канон глубоко въелся:-)

> VV> Вопрос вот какой - есть ли "культурные образцы", позитивные примеры 
> VV> альтернативных практик, не просто в форме книг или статей, а именно в 
> VV> форме документации, прилагаемой к продукту?
> 
> Позитивных нет. Или программы стремятся к "продуктовости" (и, в этом
> смысле, к открытости), или остаются в обороте эзотерической группы с
> "устной" традицией. Обратите внимание на слово "стремятся". У объемной
> документации, как и у программной системы, завершения не бывает,
> бывают только релизы.

О, да. Все же документация - не продукт, а процесс:-)

> Помимо всего прочего, "программный продукт" есть термин (даже
> ГОСТированный), который по определению предполагает "канон"
> документирования, подобный вышеописанному.
> 
> VV> С другой стороны, можно действительно считать, что "документация не 
> VV> продукт, а процесс", и начать с наращивания tips&tricks.
> 
> Вроде бы, весь опыт в этом направлении, по большому счету, только
> негативный. Например, все книжки на букву "Л", не исключая даже Уэлша
> с Федорчуком.

Надо полагать, что позитивный опыт - в книжках на букву "Ю"?

-- 
С уважением,
Вадим