[docs] Re: документация для нового Junior'а

[Vitaly Ostanin]

On Fri, 30 Jan 2004 20:25:46 +0300
"Oleg A. Paraschenko" <olpa на xmlhack.ru> wrote:

>   Привет!
> 
> On Fri, 30 Jan 2004 22:32:16 +0300
> Kirill Maslinsky <kirill на altlinux.ru> wrote:
> 
> > 
> > Добрый день!
> > 
> > Прошу прощения за "ответ с задержкой", но тема-то остается
> > актуальной. 
> > 
> > > > Да, действительно. Но выглядит-то все равно не очень. 
> > > > Я, честно говоря, вообще сомневаюсь, что на стандартном
> > > > формате можно делать красивые книги. В каждой книге есть
> > > > специфические задачи, и они должны решаться
> > > > специфическими средствами. 
> > > 
> > >   Многие специфические задачи можно и нужно
> > >   автоматизировать.
> > 
> > Именно к этому я и клонил, признаться. Я недавно начал
> > работать с документацией, и поэтому только составляю для себя
> > список задач, которые специфичны именно для документации ALT
> > и не реализованы ни в DocBook, ни где-либо еще, так, как
> > именно бы хотелось.  И тут у меня есть все шансы наступать на
> > старые грабли и бродить известными путями, поэтому прошу всех
> > давних участников меня предупреждать от ошибок и ссылать в
> > архив рассылки, особенно буду благодарен за ссылки
> > конкретные. 
> 
>   С этим сложнее. Давние участники сдают сессию.

Ну не все же :) Кстати, я сдал. Причём обе, и вместе с гос.
экзаменом :)

>   Для записи знаний предлагалось wiki, но по различным причинам
>   эта система не появилась:
> 
> http://www.google.com.ru/search?q=wiki+%22docs+mailing+list%22+site%3Awww.altlinux.ru

Дело наверняка не в ресурсах, а в наполнении. Если есть реально
готовый заняться, думаю, в ALT найдётся место под ещё один
web-ресурс.

Лично мне идея wiki не нравится тем же, что и FAQ - это временные
затычки. Не должно быть повторяющихся вопросов - они появляются
из-за затянувшихся ошибок. И не должно быть слабо
структурированной свалки сведений. Нужна хорошая, обширная
документация с удобным механизмом поиска и ссылок. 

Собственно, FAQ/Wiki - это выжимки из общей документации, которые
могут быть получены и поиском/структурированием по разделам
знаний.

Это всё IMHO :)

> > Что же касается автоматизации, то ее логично основывать на
> > максимально выверенной и локализованной под специфику ALT
> > разметке, но пока в тех текстах, которые я видел, -- увы! --
> > все очень и очень вразнобой. 
> 
>   Про ошибки имеет смысл писать также в багзиллу.
> 
> > А местами принцип логической разметки явно не соблюдается,
> > например,<emphasis>GNU General Public License</emphasis> -- ?
> 
>   Да, это ошибка.
> 
> > Но это еще частность... Отсюда, мне кажется, многие проблемы
> > с плохим качеством при конвертации в другие форматы.
> > 
> > Скажите пожалуйста, где, кроме alt-entities есть
> > специфические для ALT элементы разметки? (чтобы ничего не
> > упустить из того, что уже сделано)
> 
>   Всё из /usr/share/xml/alt-entities и больше, кажется, ничего.

Только в alt-entities и то, что описано (будет описано) в 
docs-howto.

<skipped/>

-- 
Regards, Vyt
mailto:  vyt на vzljot.ru
JID:     vyt на vzljot.ru
----------- следущая часть -----------
Было удалено вложение не в текстовом формате...
Имя     : отсутствует
Тип     : application/pgp-signature
Размер  : 189 байтов
Описание: отсутствует
Url     : /pipermail/docs/attachments/20040201/d7971ed7/attachment.bin