[docs] Re: mozilla.ru

[Vadim Vinichenko]

Maksim Otstavnov пишет:
> Hello Vadim,
> 
> Tuesday, March 18, 2003, 1:13:42 AM, you wrote:
> 
> 
>>>Непонятно, зачем клеймить, и неочевидна истинность второго члена.
> 
> 
> VV> Дело в том, что это написано в контексте обсуждения "монументальных" 
> VV> руководств к "тяжелым" гуевым программам и средам (GNOME, KDE, Mozilla).
> 
> Для меня проблема скорее в самой "тяжести" (т.е. архитектурных
> ошибках) софта.

Ну, по крайней мере, они повернуты к пользователю кучей более или менее 
разрозненных функций и настроек. Которые могут быть более или менее 
логично рубрицированы разработчиком и писателем, но это все равно 
ползучий эмпиризм - никакой выраженной идеологии за ними не стоит. Что 
касается ошибочной архитектуры - мне трудно представить себе, как мог бы 
выглядеть, например, аналог Mozilla c "правильной" архитектурой или 
некий идеологически правильный "не-аналог", который отменил бы собою 
потребность в ней. Весьма вероятно, впрочем, что это мои проблемы.

А вот интересно, Emacs тоже повернут к пользователю кучей разрозненных 
функций и настроек? (То, что у него "внутри" разумная архитектура, мне 
известно). К сожалению, не имею достаточного опыта работы с ним, чтобы 
ответить на этот вопрос.

> VV> У меня нет сомнения в том, что Library Reference к ЯП должна содержать
> VV> описание всех функций, даже если любой отдельно взятый пользователь 90% 
> VV> из них никогда использовать не будет, и они "загораживают" ему полезные 
> VV> 10%.
> 
> Я хоть убей не понимаю, почему "загораживают". Функция указания, что
> требуется чаще, что реже, что важно, а что --- не очень --- это
> функция гайда, который читают. Референс не читают, в него заглядывают,
> как в словарь, но при этом есть "алфавит", по которому можно искать
> "статьи" в "словаре", изложенный в гайде.

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

> VV> Есть подозрение, что для таких программ нужен некий agile documenting,
> VV> облегченный подход к документированию, исходящий из того, что GUI в 
> VV> значительной степени самодокументирован.
> 
> apt-get remove им нужен, если честно :)
> 

Это, безусловно, идеологически чистый способ:-) Тем не менее, если я иду
по пути компромиссов и хочу посвятить некоторое время документированию 
какой-либо гуёвины, для меня пока остается открытым вопрос: каковы 
должны быть формат и принципы составления документации, чтобы я потратил 
свое ограниченное время наиболее эффективно? Эффективно - с точки зрения 
совокупной полезности получившейся документации для пользователя.

>>>VV> С другой стороны, можно действительно считать, что "документация не
>>>VV> продукт, а процесс", и начать с наращивания tips&tricks.
>>>
>>>Вроде бы, весь опыт в этом направлении, по большому счету, только
>>>негативный. Например, все книжки на букву "Л", не исключая даже Уэлша
>>>с Федорчуком.
> 
> 
> VV> Надо полагать, что позитивный опыт - в книжках на букву "Ю"?
> 
> Книжка на "Ю" пишется в предположении, что у читателя есть доступ к
> установленной/администрируемой системе. Поэтому в нем все по порядку.
> 
> Книжки на "Л" в массе своей писались в предположении, что у читателя
> нет доступа к установленной/администрируемой системе. Поэтому в них
> перемешаны главы, образно говоря, про пикап и главы про технику секса.
> 
> Есть предположение, что пикапу и технике секса _одновременно_
> научиться нельзя или, по крайней мере, что это неэффективно. Нужно
> обучиться технике (эффективным приемам работы) на доступном партнере,
> а потом целенаправленно осваивать пикап (администрирование).

Класс:-)

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

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