[docs] Re: M24 docs impressions

[Vitaly Ostanin]

Kirill Maslinsky пишет:
> Добрый вечер.
> 
> 
>>Наконец добрался до привезённой Виталием Липатовым коробки с 
>>Мастером 2.4 (за что Виталию огромное спасибо).
>>
>>Про документацию:
> 
> 
> Спасибо за Ваши замечания, Вы дернули за несколько вопросов, которые давно стоило обсудить. Хотя по набору Ваших впечатлений кажется, что книжки в коробке 2.4 -- это скорее повод обсудить организационное неустройство docs, чем собственно содержание книжек. 

Это и не тот, и не другой повод - это просто впечатления.

> Ну ладно, неустройство так неустройство.
> 
>>Не нашёл списка разработчиков, участвовавших в создании M24.
> 
> Я его выпустил. Виноват.

Можно воспользоваться errata, или как это правильно называется.

>>Не нашёл в книгах ни одного упоминания о проекте docs и его 
>>некотором участии в создании документации. Даже в главе 
>>"Документация" руководства по установке. Однако редактор и 
>>верстальщик указаны в каждой книге.
> 
> Некоторое время назад я спрашивал здесь в рассылке о каком-нибудь тексте 
> о том, что такое проект docs, его задачи и т. п. Выснилось, что такого 
> текста нет. 

По крайней мере, известно, что такой проект есть, и в его рамках 
(если это так) готовится документация. Например, с использованием 
стилей, созданных в рамках проекта.

> Честно говоря, похоже, что нет и чёткого (и единого!) мнения у 
> участников, где проект docs начинается, где кончается, что сделано в его
> рамках, а что уже нет. 

Кирилл, это мнение должно быть у Вас, как у руководителя проекта.

Если не хватает информации, всегда можно уточнить детали. В 
случае распределённого проекта можно и не дождаться готового 
документа с историей, задачами и проблемами проекта.

> Поэтому в книжках ничего нет о проекте -- непонятно,
> что писать. Есть тексты документации, есть их авторы -- это понятно. 
> 
>>Печалит тот факт, что подготовка документации, даже состав и 
>>содержание книг - не обсуждались и не озвучивались в docs at .
>>
>>Лично мне было бы приятно видеть своё имя в списке авторов, если 
>>бы оно не относилось к статье о Psi 2,5-летней свежести, которую 
>>в своё время я не отдал даже на литправку по причине дикой 
>>устарелости.
> 
> (Тут я немного перенёс -- связанные замечания)
> 
> Действительно важная проблема: оценка адекватности текстов.
> Нескольким авторам я написал запросы относительно их текстов: насколько 
> они устарели, нельзя ли обновить, и включать ли вообще. Далеко не от
> всех я получил ответ, никто (кроме Саши Прокудина) не стал ничего обновлять.

Стоит ли говорить, что я не получал такого запроса...

> Действительно, так было сделано не со всеми текстами. Но как это себе
> представить: писать каждому автору лично или про каждый текст в рассылку?

В рассылку. Можно посмотреть в архивах, как это делалось для 
документации к M22. Собирались и выкладывались беты pdf книг, 
обсуждался состав, качество, баги документации.

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

Без заданного вопроса шансов дождаться ответа ещё меньше.

> По сходным причинам не было и обсуждения в docs@ состава книжек. 
> Не совсем очевидно, как организовать такое обсуждение, чтобы оно было
> конструктивным. Просто сообщения с моей стороны 
> о ходе работы, принятом оглавлении и т. п., на тот случай, если у читателей
> рассылки возникнут замечания и соображения? 

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

"В $CVSROOT/books/master24/ собраны книги для коробочной версии 
M24, нужно вычитать/исправить/обновить то-то, в печать будет 
отдано ориентировочно тогда-то, тестовые сборки в pdf выложены 
там-то, для сборки использованы стили db2latex-alt."

> Тогда встаёт вопрос, 
> о чём именно сообщать. Если сформулировать ответ на этот вопрос, можно
> организовать информацию о текущей работе, состоянии текущих текстов, возможно,
> это эффективнее будет делать не в форме рассылки, а на сайте docs.
> 
> Вышеперечисленные вопросы, на мой взгляд, по крайней мере отчасти 
> связаны с тем, что круг обязанностей участника проекта docs совсем 
> не определён. Поэтому, написав в docs@, никогда точно не знаешь, каков 
> будет результат и будет ли вообще. 

Это справедливо для рассылки любого добровольного проекта.

> Позволю себе сравнить ситуацию 
> с devel at . Есть круг обязанностей мантейнера (есть соответствующий документ). 
> Если пакет перестал собираться -- письмо мантейнеру и в devel at . Всё ясно.
> Обязанности же автора по отношению к документу... Должен ли автор что-то
> сделать, если документ устарел и перестал соответствовать реальности? 

Вряд ли автор что-то должен документу, но автор может захотеть 
его обновить по хорошему поводу.

> Схема orphaned/obsolete здесь не лишена смысла. 
> Нужна чёткая схема работы с авторами -- недавно это здесь обсуждалось, 
> пока, правда, без достаточного числа конкретных предложений. 
> 
>>То же самое по поводу технологии подготовки книг. Некоторые 
>>знакомые баги наводят на мысль, что использовались стили 
>>db2latex-alt, но уверенности нет.
> 
> Именно так. Мы с Вами давно уже обсуждали существующую технологию, 
> и возможности по её изменению, собрались даже было что-то сделать,
> но не нашлось времени ни у Вас, чтобы сделать, ни у меня, чтобы
> завести разговор ещё раз. В итоге Вы мне сами посоветовали использовать
> db2latex-alt, чему я честно последовал. 

Вы меня удивляете. Я действительно это посоветовал? Можно 
посмотреть дату и тему того письма?

Я неоднократно высказывал мнение о кривизне db2latex и о том, что 
качественную печатную документацию нужно готовить с помощью XEP, 
на который ради такого случая можно разориться публикующей фирме.

> О проблемах существующей технологии я пишу периодически, пока 
> предложений очень немного. 

А зачем их много? Могу повторить своё представление о проблемах 
существующей технологии:

Проблема первая и главная - отсутствие свободного и массово 
удобного редактора XML. Решается написанием собственного 
редактора и конвертацией добровольцами из других форматов. Или 
ожиданием улучшений в этой области.

На эту и другие темы хорошо пишут здесь:
http://www.badgers-in-foil.co.uk/projects/docbook-css/LDP-Author-Guide/ldp-author-guide-concat.xml

Кстати, это статья прямо в DocBook, mozilla/opera его показывают 
с помощью CSS. Про konqueror не знаю.

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

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

Это ошибочное мнение.

<skipped/>

-- 
Regards, Vyt
mailto:  vyt at vzljot.ru
JID:     vyt at vzljot.ru
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 256 bytes
Desc: OpenPGP digital signature
Url : http://lists.altlinux.ru/pipermail/docs/attachments/20041208/b4843070/signature.bin