[docs] M24 docs impressions

[Kirill Maslinsky]

Добрый вечер.

> Наконец добрался до привезённой Виталием Липатовым коробки с 
> Мастером 2.4 (за что Виталию огромное спасибо).
>
> Про документацию:

Спасибо за Ваши замечания, Вы дернули за несколько вопросов, которые давно стоило обсудить. Хотя по набору Ваших впечатлений кажется, что книжки в коробке 2.4 -- это скорее повод обсудить организационное неустройство docs, чем собственно содержание книжек. Ну ладно, неустройство так неустройство.

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

Я его выпустил. Виноват.

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

Некоторое время назад я спрашивал здесь в рассылке о каком-нибудь тексте 
о том, что такое проект docs, его задачи и т. п. Выснилось, что такого 
текста нет. Честно говоря, похоже, что нет и чёткого (и единого!) мнения у 
участников, где проект docs начинается, где кончается, что сделано в его
рамках, а что уже нет. Поэтому в книжках ничего нет о проекте -- непонятно,
что писать. Есть тексты документации, есть их авторы -- это понятно. 

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

Действительно важная проблема: оценка адекватности текстов.
Нескольким авторам я написал запросы относительно их текстов: насколько 
они устарели, нельзя ли обновить, и включать ли вообще. Далеко не от
всех я получил ответ, никто (кроме Саши Прокудина) не стал ничего обновлять.
Действительно, так было сделано не со всеми текстами. Но как это себе
представить: писать каждому автору лично или про каждый текст в рассылку?
Выглядит довольно нерационально, особенно учитывая тот факт, что сроки 
поджимают, и нет возможности дожидаться ответа от каждого автора.

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

Вышеперечисленные вопросы, на мой взгляд, по крайней мере отчасти 
связаны с тем, что круг обязанностей участника проекта docs совсем 
не определён. Поэтому, написав в docs@, никогда точно не знаешь, каков 
будет результат и будет ли вообще. Позволю себе сравнить ситуацию 
с devel at . Есть круг обязанностей мантейнера (есть соответствующий документ). 
Если пакет перестал собираться -- письмо мантейнеру и в devel at . Всё ясно.
Обязанности же автора по отношению к документу... Должен ли автор что-то
сделать, если документ устарел и перестал соответствовать реальности? 
Схема orphaned/obsolete здесь не лишена смысла. 
Нужна чёткая схема работы с авторами -- недавно это здесь обсуждалось, 
пока, правда, без достаточного числа конкретных предложений. 

> То же самое по поводу технологии подготовки книг. Некоторые 
> знакомые баги наводят на мысль, что использовались стили 
> db2latex-alt, но уверенности нет.

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

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

> Из мелкого занудства:
Позвольте на мелкое занудство ответить мелким занудством ;)

> В руководстве по установке есть глава "Что такое ALT Linux" с 
> описанием ALT Linux Team и Сизифа. При этом есть отдельная
> книга "ALT Linux Team и проект Sisyphus".

Не вижу противоречия. У раздела и у книжки -- совсем разные задачи,
содержание, и, возможно, даже аудитория (может, и не всякий полезет
в "ALT Linux Team", кто полезет в руководство по установке). 
Так что пусть.

> На задней обложке книги "ALT Linux Team и проект Sisyphus" вместо 
> дефиса должно стоять длинное тире.
Если уж на то пошло, то на задних обложках всех книжек во всех 
случаях дефис.  Виноват, вычитывал обложки удалённо, в формате 
plain text, так что заменить не мог. Впрочем, дефис в этом 
шрифте не очень куцый, можно принять и за короткое такое тире ;)

-- 
Kirill Maslinsky
ALT Linux Team * Documentation Project