[docs] docs plans

[Anton Farygin]

Michael Shigorin wrote:
> On Wed, Dec 24, 2003 at 01:01:15AM +0300, Anton Farygin wrote:
> 
>>>>В документации для Мастера (в руководстве администратора) очень
>>>>не хватает описания именно особенностей дистрибутива. 
>>>
>>>Неочевидностей... "см. alt faq на atmsk.ru"?
>>
>>Нет.  IMHO именно описание особенностей.
> 
> 
> "Особенности" бывают разные: +/- ожидаемые, но светящиеся (это
> то, что интересно при делании выбора => PR/реклама) и важные, но
> не всегда очевидные или ожидаемые.  Которые нужны в изложении
> администратору.
> 
> Бишь писать ему, что вот есть TCB или apache -- не особенно
> осмысленно.  А вот писать, чем это хорошо (и каким боком вылезет
> с PowerChute или Webmin, ну или про то, как прикручен mod_perl и
> почему) -- нужно.

И то и то нужно. Иначе он не поймет, что есть TCB ;-)

> 
> 
>>И вообще, на мой взгляд корректная документация по программному
>>продукту должна предоставлять пользователю:
>>1) Справочник по программам/опциям
> 
> 
> Чушь полная.  На это есть дохренищу документации хоть на русском,
> хоть на фарси, не говоря об английском.  Начиная с manpages,
> между прочим.

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


> 
> Вот соответствие "задача <-> программы" -- необходимо.

Это и есть эффективное использование.

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

Вот тут ты не прав. Только эффективное использование бывает... все 
остальное - поделки.

> 
> 
>>Это имеет отношение ко всем составным частям документации,
>>включая руководство администратора или разработчика.
> 
> 
> Здрасьте.  Зачем разработчику то, что он и так прочтет в любом
> manpage на любом линуксе (да еще за его же деньги), если не
> изложено более важное -- что тут не так, как у других?  Что тут
> удобнее, надежнее, безопаснее, слаженнее?

Да ну ? Найди мне manpage по QString ?

Или покажи пример документации, в которой описано, как на лету сменить 
разрешение в XFree ?


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

Правильно.. а никто и не говорит, что все будет в печатном варианте.

Для печатного варианта - нужен способ формировать из различных разделов 
online документации - печатный вариант.

> 
> Хочешь пройти по этим же граблям?  Подумай, сколько денег
> угроблено на _такую_ документацию и кому она нужна сейчас.
> 
> 
>>В концепции, предложенной Сашей я не увидел подобного подхода к 
>>составлению документации. Концепция, скорее, предлагает
>>пользователям ряд статей, объединенных по тематикам и
>>описывающих те или иные кусочки системы.
> 
> 
> И это правильно.  И претензий к Сашиному видению вопроса у меня
> _нет_ (глобальных).  А к твоему -- есть.  Глобальные.

Т.е. - ты хочешь сказать, что документация, идущая с Master 2.2 - тебя 
полностью устраивает ?

Rgds,
Rider