ru.unix.bsd

 
 - RU.UNIX.BSD ------------------------------------------------------------------
 From : Valentin Nechayev                    2:5020/400     16 Dec 2004  01:46:31
 To : eugen@grosbein.pp.ru
 Subject : Re: VPN
 -------------------------------------------------------------------------------- 
 

 >>> Eugene Grosbein wrote: 
 
  VN>> 1. Howto могут описывать далеко не только готовые конфиги. В мире Linux
  VN>> howto дают:
  VN>>  - Описание понятий, используемых в той или иной области, включая
  VN>>  определения,
  VN>>    граничные признаки, бытовые примеры и точные формулировки.
 EG> Этому не место в Howto (или, если угодно, это уже не Howto).
 EG> Этому место в книгах по предметной области и в документации на
 EG> конкретный софт.
 
 Книги по предметной области пропустим. А вот "документация на конкретный
 софт" - это уже показательно. HOWTO - не часть документации?;))
 OK, я согласен на то, что разделение несколько нелогично, но дело тут в том,
 что линуксовые howto составлялись часто в отрыве от конкретных продуктов,
 со ссылкой на целый комплект продуктов для одной цели.
 Точно тот же подход мы видим во фрёвом handbook'е: идёт сначала общее
 описание, что это такое и для чего его едят, а потом уже переход к
 конкретным реализациям (программы, конфиги и так далее).
 И это правильно - не надо кормить документацией по особенностям ключей
 чего-то, пока непонятно, накойхер оно вообще нужно.
 
  VN>> В частности, для конфигов это может
  VN>>    выглядеть как "если вам нужно XXX, скажите option xxx. Если Вам нужно
  VN>>    YYY,
  VN>>    скажите option yyy, но если написано option ttt, это даст совершенно
  VN>>    неожиданный эффект - YYY превратится в ZZZAAA".
 EG> FAQ? В качестве дополнения к тому же самому, изложенному в доке.
 EG> По сути, донесение (чаще потребной) информации в другой форме.
 
 Чтобы стать FAQ, надо быть действительно часто наступаемой граблей.
 Для этого надо быть 1) граблей, 2) часто наступаемой;)
 Второе условие здесь скорее всего не выполняется.
 
 Hу и к тому же держать в FAQ то, чего нет в других местах документации
 (не в смысле "описано другими словами", а в смысле "нет вообще") - очень
 плохой метод построения документации. Так нельзя.
 
  VN>>  - Типичные грабли.
  VN>>  - Методы диагностики и лечения.
  VN>> Hи одно из них не сводится к голому примеру конфига.
 EG> Это все должно быть в системно изложенной документации. Или Howto
 EG> в линуксовом мире уже не ответ на "how to?", а по сути дока?
 
 Я не ограничиваюсь линуксовым стилем. Hо в нём это не полная документация,
 это общее описание на общепонятном уровне плюс действительно howto.
 То есть дока без мана и справочников ;)
 
  VN>> 2. Вопрос _воспитания_ таких зверей не ограничивается вопросом ограничения
  VN>> воплей на выдачу правильных конфигов. Проблема диагностики, например
  VN>> (которая
  VN>> вообще почему-то замалчивается, а множество народа просто не понимает
  VN>> значения правильной диагностики) станет столь же остро в этом случае.
  VN>> Выход один - посылать нафиг с такими вопросами в район smart-questions.
 EG> Угу. А может, квинтэссенцию smart-questions в FAQ эхи?
 
 Это изврат получится. FAQ всё-таки рассчитан на ответы в несколько строк.
 Уже полстраницы для него многовато. А даже основные тезисы из smart-questions
 вряд ли можно ужать менее чем в страницу.
 
 В качестве варианта - сделать выжимку размером менее 10K и кидать её
 два раза в месяц.
 -netch-
 --- ifmail v.2.15dev5.3
  * Origin: Dark side of coredump (2:5020/400)
 
 

Вернуться к списку тем, сортированных по: возрастание даты  уменьшение даты  тема  автор