[docs] ВНИМАНИЕ: отчёт и насущные проблемы

[Alexandre Prokoudine]

Kirill Maslinsky пишет:

> При этом есть некоторые привходящие обстоятельства:
> 
> * В docbook.dtd около 400 элементов. Изучение docbook -- большое сложное дело.
> * Авторов, пишущих в docbook, фактически нет среди авторов текстов нашей 
>   документации. Есть авторы, которые готовы писать и обновлять тексты, их
>   тексты нужны, но они обычно не готовы писать и поддерживать их в docbook. 
> * "Корпоративный" docbook подразумевает ряд требований, которые не входят в 
>   docbook, сформировались в моей голове из практики, и, к сожалению,
>   пока нигде не описаны.
> * Нигде не оговорено, какую именно работу по доведению документа от
>   исходного текста до пригодного "в модули" документации ALT согласны 
>   брать на себя участники проекта. Фактически, нет распределения 
>   ответственности.
> * Время на выпуск релиза очень невелико сравнительно с объёмом работ.
> 
> Поэтому получается, что:
> 
> - Перед выпуском появляется какое-то количество "сырых текстов";
> - Перед выпуском резко (или постепенно) устаревает часть существующих текстов;
> - Непонятно, кто за какие тексты отвечает, авторы свои тексты доводить 
>   до конечного состояния не будут. Согласование в рассылке, кто что и 
>   когда будет делать потребует весьма много времени (рабочего времени
>   выпускающего, в частности). И даже если дождаться такой правки, 
>   при этом ещё останется огромная ручная работа, которую всё равно 
>   делает один человек. Он не успеет её сделать, если получит 
>   правку в последний день.

Кирилл, извини, но я не вижу никакой прямой связи между количеством 
тегов в Db/XML и наличием сырых текстов. На моей памяти не меньше пяти 
человек просили простым русским языком дать им вводную документацию по 
докбуку. Её так никто и не написал. Потенциальные авторы на это 
посмотрели и быстро увяли. Это раз.

Два. "Сырые тексты" прямо перед релизом обычно не появляются. Обычно они 
обнаруживаются в таком состоянии. Объяснение чему всем прекрасно 
известно: time, time, time... Если же ты имеешь в виду в срочном порядке 
написанные к релизу доки, то их включения в релиз, имхо, стоит избегать. 
Впрочем, это зависит от компетенции автора и его владения родным языком.

Три. Насколько я заметил (поправь меня если я ошибаюсь), вряд ли можно 
назвать дистрибутив ALT Linux, вышедший согласно расписанию. Это всегда 
добавляет проблем при планировании расхода время и распределении 
приоритетов. В условиях неопределённости мотивация контрибьюторов имеет 
весьма нездоровую, но легкопредсказуемую тенденцию сам знаешь к чему.

Четыре.
Четыре-один: Есть поддерживаемые тексты.
Четыре-два: Есть тексты, авторы которых до сих пор неизвестны.
Четыре-три: Есть авторы, которые про необходимость обновления док ничего 
не знали (например, Виталий Останин + Psi). Я лично не помню, чтобы в 
этот список рассылки постилось содержание хотя бы одной из книжек. 
Впрочем, пару месяцев я был отписан.

Пять. Вроде бы давно уже - года полтора как - было оговорено, что роль 
релиз-менеджера документации берёт на себя Виталий Останин. В таком 
случае меня слегка удивляет, что ты пишешь:

> Таким образом получилось, что всю работу по выпуску документации -- от 
> исходного текста до пакетов и макетов -- почти исключительно делал один 
 > выпускающий. Качество от этого, естественно, страдает.

Очевидно, я упускаю какой-то важный организационный момент :)

> => Нужно хранилище исходных текстов в тех форматах, которые удобны
> их авторам, которое будет частью docs. Из этого хранилища любой 
> волонтёр сможет выбрать текст и сделать его пригодным для включения 
> в общий пакет документации ALT.

Где будет располагаться этот ресурс?

> => У каждого текста должен быть ответственный сопровождающий (аналог 
> мантейнера), отвечающий за соответствие текста формальным и содержательным
> требованиям.

При всей красивости идеи реальность такого сценария сомнительна. Одно 
только "Руководство пользователя" насчитывает 16 глав на различные темы. 
Я теоретически могу представить себе пару мегагиперсопровождающих, 
который возьмут на себя по три главы из него. Что делать с остальными 
десятью главами? А ещё с тремя книгами?

> => Нужно организовать редакторский цикл для содержательной правки текстов
> на уровне Автор текста -- Ответственный за включение текста в документацию 
> ALT. Этот редакторский цикл должен быть по возможности публичным, чтобы 
> свои замечания по содержанию могли оставить максимальное количество 
> заинтересованных и компетентных людей.

Т.е. ты предлагаешь замкнуть доводку документа на автора и 
ответственного за документ автора? А кто будет контролировать 
ответственного?

> Сам формат может быть любым, например, подмножество docbook. Это 
> вопрос для обсуждения. В следующем письме я попробую сформулировать
> требования, которым должен удовлетворять формат, чтобы из размеченных
> в нём документов могла получиться и гипертекстовая, и печатная 
> документация.

Про Simplified Docnuke я ниже/выше по треду уже писал.

А.П.