[docs] docs status

Vadim Vinichenko vnv на 14000.ru
Ср Ноя 13 21:26:56 MSK 2002


aen пишет:
> Vadim Vinichenko wrote:
> 
> 
>>Мне представляется, что помещать в документацию к _дистрибутиву_
>>руководства по языкам, даже "вводного" характера - дорога в никуда. На
>>этом пути нет разумного предела, где можно остановиться, всегда чей-то
>>хвост будет ущемлен, и попросту дублируется работа издательств. 
> 
> Может быть, стимулируется?
> Скажем, хорошо бы иметь кнгу про Mozilla, но пока ее нет -- пусть будет
> развернутая статья в документации.
> 
>>
>>По языкам я бы считал разумным иметь одну обзорную статью, кратко
>>характеризующую языки (по крайней мере, основные), входящие в
>>дистрибутив, и _круг задач_, для которых применим (оптимален) каждый
>>из них. По-моему, делать это нужно. Много ли счастливых обладателей
>>Мастера знают, что такое Ocaml и для чего он может быть полезен? Пара
>>абзацев на язык, возможно, для каждого языка - отсылки на дальнейшую
>>информацию.
> 
> 
> И никто не обратит внимания. Есть ли надежда увидеть в обозримом будущем
> книгу по Ocaml на русском?
> У нас отсутствует очень важный компонент "просветительства" -- серьезные
> журналы и/или альманахи для разработчиков и профессиональных пользователей.
> Между книгой и "обзорной статьей" есть именно то, что реально читается и
> действительно полезно. Где это публикоавать?
> Будет ли полезна статья по Python? по Mozilla? по Ocaml? Будет! Нарушит
> ли она стройный вид документации? Возможно.

1. Думаю, что краткий обзор основных сокровищ дистрибутива - все же must 
have. И я не уверен, что никто не заметит его содержания, хотя многие, 
конечно, пропустят. Вопрос о том, что вообще скрывается в недрах 
дистрибутива, возникает у пользователя не так уж редко. Правда, он 
особенно обостряется при встрече с селектором пакетов в программе 
установки, когда не до чтения обзорных статей:-)

2. Мне все же интуитивно видится некоторая граница между прикладным 
пакетом (будь то Mozilla, Apache или среда разработки), и языком 
программирования, - хотя интуиция может меня подводить. Я легко могу 
представить себе пользователя, который осваивает или настраивает 
названные пакеты с руководством в руках, но изучает язык...

Хотя, если с дистрибутивом придет полноценное руководство, - почему нет? 
     Другой вопрос - на сколько полноценных руководств хватит ресурсов 
при подготовке дистрибутива?

Серьезные обзорно-просветительские статьи - да, определенный смысл это 
имеет, в том числе и по языкам. Хорошо бы только, чтобы это 
действительно были обзорно-просветительские статьи, а не 
"недоруководства". Кроме того, факт наличия таких статей в документации 
надо будет как-то специально анонсировать - есть вероятность того, что 
пользователь (а поскольку это - документация к дистрибутиву, то читатель 
у нас, в первую очередь, пользователь) такой текст просто пропустит.

Кроме того, хорошо бы понять (в перспективе), каковы относительные 
приоритеты в треугольнике:

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

А вообще, есть ли какой-нибудь vision желательного состояния и состава 
документации ALT, кроме положения о том, что "документации мало не 
бывает"? (Это скорее вопрос для дальнейших размышлений, чем требование 
немедленного ответа).

<skipped/>

--
С уважением,
Вадим




Подробная информация о списке рассылки docs