[docs] docs plans

Чт Дек 25 21:18:42 MSK 2003

On Thu, Dec 25, 2003 at 03:48:43PM +0300, Anton Farygin wrote:
> >Бишь писать ему, что вот есть TCB или apache -- не особенно
> >осмысленно.  А вот писать, чем это хорошо (и каким боком
> >вылезет с PowerChute или Webmin, ну или про то, как прикручен
> >mod_perl и почему) -- нужно.
> И то и то нужно. Иначе он не поймет, что есть TCB ;-)

Я ж не спорю.  Только _администратору_ (да и большинству
программистов) оно особенно и незачем -- всего не объять.

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

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

А ты собираешься документировать все и вся.  Повторю для второго
уха -- у больших и толстых UNIX-вендоров это сто лет как
перестало практиковаться.  И тут выходит rider, весь в белом, и
выносит из подсобки гору Правильно Документации Всего и Вся...

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

Нет.  Это мостик к использованию вообще.

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

Слушай -- определи-ка свое "эффективное использование", а?  А то
что-то у тебя третья ортогональная трактовка вылазит.

IMCO, э.и. -- это применение компетентным в предметной области
пользователем предметной области адекватной ей программы.

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

Писать документацию про эффективное использование Всего и Вся --
задача невыполнимая еще более по своей сути, чем то, что ты выше
предлагал.  Это значит быть _экспертом_ в каждой описываемой
области.  Ну поди напиши доку по э.и. cinelerra или haskell
какого.

А еще лучше -- почитай какие курсы, поймешь, чем люди живут.
И что реально полезно.  Заодно развеешься :-)

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

http://doc.trolltech.com/3.2/qstring.html (также в 3.1)
http://default.co.yu/~bc/rtfm/index.php -> QString

Нагуглил по "QString manpage" за две с хвостиком минуты.

Если ты хочешь сказать, что man QString ее не знает -- так это
проблемы (недо)упаковки.

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

google://xrandr (I'm lucky).

А вот _связь_ между этим ключевым словом и действием и стоит
указать; плюс ссылки на программы/аплеты.  Разработчику хватит
ключевого слова, а пользователю -- названий пакетов.

[еще одно связанное соображение, обсуждавшееся на позапрошлом LF,
skipped]

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

Тогда в каком -- электронном?  Так создать-то тоже денег стоило и
стоит.  А вот стоит ли изобретать велосипед?  Впрочем, для вас,
видимо, стоит -- смотрю, прямо региональный вид спорта.

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

Да это все хорошо.  Но что ты думаешь делать с тысячами
man-страниц (это уже готовые материалы, между прочим), которые
"всего лишь" надо перевести и заодно переформатировать в тот же
DocBook?

Сделай одну, оцени объем труда -- а потом корректируй
предложение.

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

Я хочу сказать, что она как раз ближе к твоему "видению", если
это вообще можно так назвать.

И по этому пути лучше ничего не получится -- разношерстное и
разноуровневое, то до вызовов API, то "про GNOME в две строчки".

PS: интересно, когда-нибудь заметите, что архитектор и кодер --
разные люди, или так и будете все в кучу мешать?

-- 
 ---- WBR, Michael Shigorin <mike на altlinux.ru>
  ------ Linux.Kiev http://www.linux.kiev.ua/