[docs] Re: documenting make-system

[Oleg A. Paraschenko]

  Привет!

On Tue, 11 Nov 2003 19:52:45 +0300
Vitaly Ostanin <vyt на vzljot.ru> wrote:

> On Tue, 11 Nov 2003 19:32:18 +0300
> "Oleg A. Paraschenko" <olpa на xmlhack.ru> wrote:
> 
> >   Привет,
> > 
> >   думаю, что пора выкладывать описание make-файлов в cvs. Никто
> >   не против, если я добавлю его в "Принципы создания документов
> >   для ALT Linux Team Documentation" между "Преобразование в
> >   другие форматы" и "Оформление"?
> 
> Я против, по нескольким причинам. Пожалуйста, не обижайся.
> 
> Я хотел бы сам обновлять docs-howto. Он мне нравится и я ещё не
> потерял к нему интерес :)

  Тогда надо придумать, как ты будешь обновлять docs-howto. Я
стал выкладывать описание на:

http://xmlhack.ru/tmp/alt/makefiles/makefiles.xml
http://xmlhack.ru/tmp/alt/makefiles/makefiles-html-dir/index.html

  С каждым дополнительным изменением в системе make-файлов я обновляю эти
тексты. Соответственно, так как изменения будут вноситься ещё долго, то и
тексты будут меняться.


> 
> Я хотел бы вставлять в docs-howto листинги не как во вложении,

  Там не листинги, там примеры использования. Ибо лучше один раз увидеть.

> а сделанные из litprog.
> 
> Мне не нравится форма изложения в виде FAQ, текст должен был
> описательным без наводящих вопросов,

  По своему опыту -- текст должен быть описательным и равномерным только в
крайних случаях. Например, в programmer's reference (но не в guide или
manual). В данном случае у нас должно быть не reference, а всего лишь
руководство пользователя и введение в архитектуру для программистов.
Причина проста -- я думаю, что вся эта система интересна в деталях
разве что паре человек. Остальным интересно только знать, какую кнопку
надо нажать чтобы всё само сделалось как надо.


> а вопросов пока быть не
> может - новой схеме makefiles без году неделя.

  Но потенциальные вопросы известны заранее. Каждый вопрос -- это типичный
вариант использования.

> 
> Есть предложение - сначала доделать Makefiles, я (или ещё
> желающие) доделаю по ним litprog, после чего напишу описание,
> каким я его представляю.

  Предложение не нравится. Система должна передаваться пользователям
только вместе с документациий. На данный момент система есть, документация
есть, поэтому систему можно использовать. Если же написание документации
отложить, то, по-хорошему, надо отложить и внедрение системы.

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

http://xmlhack.ru/tmp/alt/makefiles/makefiles-html-dir/index.html

> 
> Пусть их будет даже два :),

  Видимо, будет. Я сейчас собираю для сайта-резюме свои работы, и этот
текст там не помешает.

> но мне бы не хотелось включать в
> docs-howto фрагмент, который по-моему мнению должен быть другим.

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

> 
> >   Текущая версия в формате html-dir -- во вложении.
> > 
> >   Ещё вопрос: а есть возможность быстро выложить обновление
> >   документации
> > на сайт? Просто при анонсировании новой возможности хотелось бы
> > сразу дать ссылку на документацию.
> 
> На docs.altlinux.ru - вряд ли. Насколько я знаю, у каждого
> разработчика в ALT есть возможность написать на admin на altlinux.ru
> с просьбой выделить место на http://people.altlinux.ru

  Не, проще у себя.

> 
> <skipped/>
> 
> -- 
> Regards, Vyt
> mailto:  vyt на vzljot.ru
> JID:     vyt на vzljot.ru


-- 
Oleg