[docs] требования к формату модуля документации

Fr. Br. George george на altlinux.ru
Ср Янв 12 12:57:40 MSK 2005


On Wed, Jan 12, 2005 at 11:21:55AM +0300, Oleg A. Paraschenko wrote:
> 
> [quote]
> Да, ещё имеет смысл разделить "создание" и "модификацию" -- если
> создать исходный документ мне, например, проще в text/plain, то
> мелко-средние правки по ходу смогу вносить и в сконвертированный
> в docbook/ALT вариант.
> [/quote]
> 
>   А проблема точно в формате? Он ли узкое место? Будут ли авторы писать
> тексты при наличие суперудобного формата?
	Авторы их пишут, что подтверждается наличием огромного корпуся
документации в Сети. Кроме того, есть ещё какое-то количество
``авторов'', которые _вынуждены_ писать тексты -- техническая поддержка,
отчёты, FAQ и прочая -- с одной стороны -- рутина, а с другой стороны --
её тоже нужно доводить до варианта, пригодного для взаимообмена и
публикации. Например, исследоватльские отчёты -- прямые кондидаты на
место в ALD. И вот ту вопрос об ``удобном редакторе'' становится как
нельзя более актуальным. Беда в том, что понятие ``удобный редактор'' --
не только эргономическое, но и психологическое, персональное. Так что в
этом ключе задача нерешаема: кому нравится поп, кому попадья, а кому
попова дочка. Поэтому остаётся мудрить над упрощённым форматом.

> > Постулат: такой формат может и должен содержать не более 7--12
> > элементов.
> 
>   Для автора, который находится непосредственно в процесее написания
> текста -- да, постулат верен. Для "Необходимой информации" -- нет.
	Почему -- нет?
> 
>   Например, [часть] DocBook для хранилища и Restructured Text для авторов
> для написания первой версии текста:
> 
> http://docutils.sourceforge.net/
	Какая [часть]? А что касается ReST, это реальный кандидат, если
потом с ним что-нибудь, кроме превращения в HTML, можно сделать будет
относительно безболезненно.

-- 
			George V Kouryachy (aka Fr. Br. George)
			mailto:george at altlinux_ru


Подробная информация о списке рассылки docs