[docs] Re: docs plans

[Anton Farygin]

Anton V. Boyarshinov wrote:
> Добрый день
> 
> On Wed, 24 Dec 2003 01:01:15 +0300 Anton Farygin
>  wrote:
> 
> 
>>И вообще, на мой взгляд корректная документация по программному
>>продукту должна предоставлять пользователю:
>>
>>1) Справочник по программам/опциям
> 
> 
> Зачем? Электронный справочник гораздо удобнее.

Продемонстрируйте мне, пожалуйста, готовый электронный справочник на 
русском языке, в котором будут одновременно лежать описания утилит ls, 
cd, grep и sed. К тому же этот справочник все-таки должен быть 
структурирован по типу применения (что бы было просто найти, с помощью 
чего это сделать).

Для примера - у нас есть классный электронный справочник man. Попробуйте 
в нем быстро найти утилиты, с помощью которых можно получить:
1) имя каталога из полного пути к файлу
2) количество строк в файле
3) утилиту, уменьшающую размер текстового файла методом замены пробелов 
на табуляцию.

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

Отчего ж ;-)

> 
> 
>>и некую книгу, рассказывающую о том как 
>>это все использовать для решения тех или иных задач.
> 
> 
> То есть первично решение задач. Именно то, о чём писал Саша.
> 

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

Rgds,
Rider