[docs] docs plans

[Alexandre Prokoudine]

Anatoly A. Yakushin wrote
> Alexandre Prokoudine пишет:
> > Привет!
> > 
> > По просьбе руководства я подготовил своё видение будущей документации для
> > дистрибутивов ALT и примерный план разделов.
> <skip>
> Позвольте внести свои пять копеек :) Просто с момента выхода ALM 2.2 и
> его внедрения у себя мне пришлось поработать в совершенно
> несвойственных качествах - админом, системным программистом,
> лектором-пропагандистом и т.п. Поэтому проблемы с документацией ощутил
> на своей шкуре. Так что это в некотором роде vox populi :)
> 
> Итак, чего на мой взгляд совсем не надо - так это вводной части - про
> Линукс вообще.  Или по основам Линукс. Есть несколько прекрасных книг
> на эту тему, и думаю, что можно просто ограничиться их перечнем. Либо
> найти свободную, или с кем-то договориться, кто сядет один и напишет.
> Но только что-нибудь приличное.
> 
> Что необходимо - это Alt-специфика. Причем рассмотреная под разными
> углами:
> 1. Первый и один из самых главных вопросов - почему именно Альт, а не
> другой дистрибутив. Что в этом дистрибутиве есть такого, чего нельзя
> получить у других. Лично мне хотелось бы видеть это на первых
> страницах. Позицию если хотите.
> Ибо язык натер, объясняя это каждый день. Пусть там будет немного PR,
> пусть это маркетинг.
> Лично мне надоели рассуждения на тему, что дескать наш пользователь
> сам все поймет и оценит. Для этого он сначала должен стать нашим. А
> обычно он убегает неопакеченный.
> Я хочу видеть это напечатанным. Чтобы этим можно было тыкать в нос
> всяким дядям.

Насколько я понимаю, это актуально в тех случаях, когда под нос тыкается
книжка из Вашей уже открытой коробки с дистрибутивом :-)

> 
> 2. Alt-специфика для администратора. Или кто-то всерьез думает, что
> надо объяснять человеку, получающему деньги за админство, что такое
> файловая система. Причем специфика должна быть описана именно в таком
> ключе - а что именно будет иметь админ, если поставит Мастера (кроме
> геморроя с wheel :) ну на эти грабли все наступают). И чего он иметь
> не будет.

Специфика ALT для админов, видимо, действительно нужна. Кто-нибудь,
имеющий опыт администриирования, хочет составить список подходящих тем?

> 
> 3. Alt-специфика для разработчика. Ну про это много говорили.

Видимо, не при мне :-) Имеются в виду первые три раздела существующего 
Руководства разработчика?

> 
> 
> А потом эта специфика должна быть конкретно описана - apt, control,
> tcb и т.д.
> 
> Что крайне необходимо, и что пришлось сделать в первые же дни после
> покупки Мастера - это описание пакетов, входящих в дистрибутив. Это
> надо либо написать, причем по группам, либо описать подробно, как
> пользователь может получить эту информацию.
> То, что очевидно для нас, абсолютно неочевидно для всех остальных. В
> качестве примера предлагаю посмотреть в сторону документации ASP, у
> них единственное, что шикарно сделано, так это описание пакетов.

Насколько я помню, оно у них в электронном виде. Это можно сделать, но
решение, IMHO, должно выглядеть следующим образом.

У каждого пакета должно быть составленное его конвоиром описание на
русском языке (часть конвоиров уже давно этим озаботилась).  После чего 
эти описания выдёргиваются скриптом в текстовый файл.

> 
> Что в первую очередь необходимо для пользователя - это подробное
> описание, как именно получать справочную информацию. С подробными
> примерами. Для man, info, принципы работы в рассылке и т.д.
> Многие находять русские HOWTO после полугода работы. Кстати, эти HOWTO
> тоже бы пересмотреть. А то там есть пошехонская старина, а многих
> свежих наработок нет.

О работе с документацией текст есть. При необходимости его можно
дописать.

> 
> Теперь то, что мне ближе всего :) - руководство по OpenOffice.
> Хотелось бы знать, кто его конкретно собирается писать и в каком виде.

Собственно, ищу желающих. Некоторые идеи на этот счёт у меня созрели, но
хотелось бы вынести их за рамки данного списка.

> Вид интересует более всего, ибо в нынешнем виде оно IMHO нафиг нужно,
> и чего там расширять и углублять, ума не приложу.
> 
> P.S. Что еще. Есть некоторое количество статей, например написанное
> мной и fatty для ШКТ, и еще мной для некоторых других изданий. Я
> думаю, что проблем с их релицензированием не будет (поговорю с
> Костинским на следующей неделе), но вопрос - нужна ли такая
> ддокументация, и если нужна, то куда ее класть и в каком виде.

Ответить на этот вопрос, не имея статей перед глазами -- задачка
недеццццкая :-)

-- 
Alexandre Prokoudine		| "When you set yourself on fire and aim 
ALT Linux Documentation Team	|  for the sky, you hope to leave behind 
E-mail: avp на altlinux.ru		|  some sparks of heat and light"
JabberID: avp на altlinux.org	|                             Neil Peart
----------- следущая часть -----------
Было удалено вложение не в текстовом формате...
Имя     : отсутствует
Тип     : application/pgp-signature
Размер  : 189 байтов
Описание: отсутствует
Url     : /pipermail/docs/attachments/20031226/9a6880db/attachment.bin