[docs] docs plans

[Michael Shigorin]

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 и
почему) -- нужно.

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

Чушь полная.  На это есть дохренищу документации хоть на русском,
хоть на фарси, не говоря об английском.  Начиная с manpages,
между прочим.

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

> 2) Описание примеров эффективного использования программ и их опций

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

У меня нехорошее ощущение, что этой каше в т.ч. в твоей голове мы
обязаны отсутствием внятной документации на выпущенные дистры.
Исправляй, блин.

> Это имеет отношение ко всем составным частям документации,
> включая руководство администратора или разработчика.

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

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

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

Хочешь пройти по этим же граблям?  Подумай, сколько денег
угроблено на _такую_ документацию и кому она нужна сейчас.

> В концепции, предложенной Сашей я не увидел подобного подхода к 
> составлению документации. Концепция, скорее, предлагает
> пользователям ряд статей, объединенных по тематикам и
> описывающих те или иные кусочки системы.

И это правильно.  И претензий к Сашиному видению вопроса у меня
_нет_ (глобальных).  А к твоему -- есть.  Глобальные.

-- 
 ---- WBR, Michael Shigorin <mike на altlinux.ru>
  ------ Linux.Kiev http://www.linux.kiev.ua/
----------- следущая часть -----------
Было удалено вложение не в текстовом формате...
Имя     : отсутствует
Тип     : application/pgp-signature
Размер  : 189 байтов
Описание: отсутствует
Url     : /pipermail/docs/attachments/20031224/c774f7fd/attachment.bin