[docs] Re: mozilla.ru

[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> нужной.

Непонятно, зачем клеймить, и неочевидна истинность второго члена.

VV> И соблюдать каноны мы здесь никому не должны.

Кто говорил в модальности долженствования?

VV> Вопрос вот какой - есть ли "культурные образцы", позитивные примеры 
VV> альтернативных практик, не просто в форме книг или статей, а именно в 
VV> форме документации, прилагаемой к продукту?

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

Помимо всего прочего, "программный продукт" есть термин (даже
ГОСТированный), который по определению предполагает "канон"
документирования, подобный вышеописанному.

VV> С другой стороны, можно действительно считать, что "документация не 
VV> продукт, а процесс", и начать с наращивания tips&tricks.

Вроде бы, весь опыт в этом направлении, по большому счету, только
негативный. Например, все книжки на букву "Л", не исключая даже Уэлша
с Федорчуком.

-- 
-- Maksim