[docs] docs plans

[Andriy Dobrovol's'kii]

Alexandre Prokoudine wrote:
> Andriy Dobrovol's'kii wrote
> 
>>
>>И да, и нет. Я и написал "в идеале". :) Читать с листа будет удобнее 
>>пока не изменится строение глаз человека. А вот объём -- таки да. 
>>Увы. Но, есть очень много програм с похожей функциональностью. 
>>Потому я и пишу "с рекомендованным применением". К тому же многие 
> 
> 
> Андрей, здесь есть одна тонкость. Мой непосредственный руководитель,
> Антон Фарыгин, предлагает при планировании документации исходить из того,
> что Master -- это срез Сизифа. Из нескольких программ в Sisyphus, 
> предоставляющих одинаковую функциональность, действительно можно выбрать 
> какую-то одну и описать решение задачи на её примере. Но, как показывает 
> печальный опыт, нет никакой гарантии, что завтра эту программу из 
> дистрибутива не выкинут, и документацию не придётся переписывать.
> 
Да. Это увы есть. :( Но, у нас пока описано настолько мало, что 
только описание самых базовых задач (на "неустранимых" пакетах) 
займет ещё немало времени. :) А дальше, "либо ишак сдохнет, либо 
шах..." Я предпочитаю решать проблемы по мере их появления. 
Идеальных планов не существует.
> Антон предлагает писать документацию так, чтобы она не была завязана на 
> конкретное приложение. Однако, таким образом мы получим документацию 
> алгоритма, т.е. чистую теорию вместо практики, в то время как решение
> задач подразумевает в гораздо большей степени практику.
> 
Я за разумное сочетание. Только список команд ничего не добавляет к 
пониманию позволяя решить конкретную задачу. Только алгоритм -- 
бывает невозможно реализовать. Нужно немного теории на примере 
практического решения. А с фундаментальными трудами и правда нет 
смысла конкурировать. Главное, чтоб читатель понял что он делает и 
зачем, и где искать дополнительную информацию.
> Разумность такого подхода представляется мне сомнительной.
> 
Ещё один труд по чистой теории врядли кому-то нужен. Особенно как 
документация к конкретному програмному комплексу.
> 
>>электронные справочники можно понять только посадив рядом их 
>>писавшего. :( Не все классные програмисты в состоянии внятно 
>>объясниться. Это тоже факт. Прост, им это не нужно.
>>Ну и последнее, никто и не ожидает, что все программы будут описаны 
>>к следующему выпуску. Это сверхзадача.
> 
> 
> Программы должны быть документированы в первую очередь сами по себе теми,
> кто в этом заинтересован. Ресурсов ALT на всеобщее документирование не
> хватит никогда.
> 
Я только за. :)
Вобщем, думаю, можно не продолжать.
-- 
Rgrds,
Andriy
*********************************************************************
email: dobr at iop dot kiev dot ua            Kyiv, Ukraine
Phone: (380-44)   265-7824            Department of Gas Electronics
Fax:   (380-44)   265-2329             Institute of Physics of NASU
*********************************************************************