[docs] Re: новый ALT Docs HOWTO: черновик раздела

[Kirill Maslinsky]

Привет еще раз!

> Хорошо, давайте так и сделаем, как временную меру. Или как форк 
> от docs-howto. Или давайте придумаем логическое разбиение 
> docs-howto на разделы. Например:

А давайте просто изменим мой текст так, чтобы он идеологически
не выбивался из docs-howto. Я, на самом деле, готов отказаться
от своего пафоса ограничивать автора в разметке, но мне кажется, 
что рекомендации, как и что стоит размечать (своего рода вводное
практическое руководство по разметке в docbook), все равно нам
понадобятся. И уже написанный раздел несложно сделать таким 
руководством, несколько изменив. 

Начиная с заголовка: заменить "Правила разметки" на "Рекомендации...", 
все предписательные замечания по тексту сделать рекомендательными, 
+ учесть Ваши замечания. Только я хотел бы оставить в тексте 
термин "понятие" (entity), в качестве воли автора, которую Вы так убеждали
меня уважать в предшествовавшем обсуждении ;)

Тогда, соответственно, куда можно поставить этот раздел в предложенном
Вами оглавлении:

> Цели проекта
> История проекта, в том числе технологическая
> Текущее состояние проекта, выбранные формат и технология
> TODO проекта (можно в виде appendix)
> Жизненный цикл документа от создания до публикации
> Создание документов
>  - краткое введение в DocBook
вот это -- практическое руководство, или это просто 
характеристика технологии DocBook со ссылками?

>  - возможно, перевод описаний основных тегов DocBook DTD, можно 
> в виде appendix
>  - принятые соглашения по стилистике
А их нет, на самом деле, да и не нужно, как мне кажется, 
потому что в этот раздел будет практически нечего 
написать кроме очевидных рекомендаций, что сленг не 
нужно использовать и что документация -- это письменная 
речь со всеми вытекающими. Любой грамотный автор и так это 
понимает, а неграмотный все равно не соблюдёт.

>  - принятые соглашения по оформлению
или это -- практическое руководство по разметке?
или же имеется в виду оформление типа "какие знаки ставить 
в конце пунктов перечисления" (у Вас, кстати, на эту тему
неверные сведения приводятся в docs-howto, нужно исправлять). 
Думаю, что какие знаки ставить можно довольно органично 
включить в практическое руководство по разметке. Так или иначе
там обсуждается содержание размечаемого текста и всякие 
типографские нюансы.

>  - примеры типовой разметки (картинки, ссылки)
это можно включить в качестве примеров в руководство? 

>  - перечисление редакторов
> Среда разработки документов
>  - описание разбиения на каталоги, их назначение
Кстати, должен обратить Ваше внимание, что в этом
отношении в docs произошли значительные изменения. 
В частности, сейчас каталоги admin, user, install в 
cvs -- полностью obsoleted, потому что изменилась 
сама структура документации. На эту тему у меня тоже 
есть черновик описания текущего положения дел, 
давайте его обсудим отдельным тредом (сейчас отправлю).

>  - работа со средой разработки (cvs, subversion, публикация 
> результатов на web)
> Описание системы публикаций
>  - общая схема
>  - документация по Makefile-ам (цели, параметры)
А можно сейчас сюда включить текст Олега Паращенко про 
Makefile'ы? Это бы нужно в Мастер.

>  - документация по XSL-стилям (назначение, возможности, параметры)
> Релизы документации (когда создаются, каким образом)
> Краткое описание сайта проекта, в том числе его внутренней структуры
> 
> Просто гибрида нового варианта и старого я хотел бы избежать.
Несомненно!

-- 
Kirill Maslinsky
ALT Linux Team * Documentation Project