[docs] docs plans

[Alexandre Prokoudine]

Andriy Dobrovol's'kii wrote
> Alexandre Prokoudine wrote:
> >Andriy Dobrovol's'kii wrote
> >
> >>В идеале, я хотел бы иметь то, что описал Антон. Но, в подаче 
> >>Александра. :) Справочный стиль по имеющимся программам с примерами 
> >>их рекомендуемого применения в контексте задач. Н...да, надеюсь 
> >>понятно выразился. :)
> >
> >
> >Вы знаете, Андрей, я не вижу никаких оснований для конкуренции с
> >существующими печатными справочниками по командам и с электронными
> >справочными файлами.
> >
> >Печатная документация должна рассказывать и объяснять, а не 
> >свидетельствовать :-)
> >
> >
> И да, и нет. Я и написал "в идеале". :) Читать с листа будет удобнее 
> пока не изменится строение глаз человека. А вот объём -- таки да. 
> Увы. Но, есть очень много програм с похожей функциональностью. 
> Потому я и пишу "с рекомендованным применением". К тому же многие 

Андрей, здесь есть одна тонкость. Мой непосредственный руководитель,
Антон Фарыгин, предлагает при планировании документации исходить из того,
что Master -- это срез Сизифа. Из нескольких программ в Sisyphus, 
предоставляющих одинаковую функциональность, действительно можно выбрать 
какую-то одну и описать решение задачи на её примере. Но, как показывает 
печальный опыт, нет никакой гарантии, что завтра эту программу из 
дистрибутива не выкинут, и документацию не придётся переписывать.

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

Разумность такого подхода представляется мне сомнительной.

> электронные справочники можно понять только посадив рядом их 
> писавшего. :( Не все классные програмисты в состоянии внятно 
> объясниться. Это тоже факт. Прост, им это не нужно.
> Ну и последнее, никто и не ожидает, что все программы будут описаны 
> к следующему выпуску. Это сверхзадача.

Программы должны быть документированы в первую очередь сами по себе теми,
кто в этом заинтересован. Ресурсов ALT на всеобщее документирование не
хватит никогда.

-- 
Alexandre Prokoudine		| "When you set yourself on fire and aim 
ALT Linux Documentation Team	|  for the sky, you hope to leave behind 
E-mail: avp на altlinux.ru		|  some sparks of heat and light"
JabberID: avp на altlinux.org	|                             Neil Peart
----------- следущая часть -----------
Было удалено вложение не в текстовом формате...
Имя     : отсутствует
Тип     : application/pgp-signature
Размер  : 189 байтов
Описание: отсутствует
Url     : /pipermail/docs/attachments/20031224/08012597/attachment.bin