[docs] Re: mozilla.ru

[Maksim Otstavnov]

Hello Vadim,

Tuesday, March 18, 2003, 1:13:42 AM, you wrote:

>> Непонятно, зачем клеймить, и неочевидна истинность второго члена.

VV> Дело в том, что это написано в контексте обсуждения "монументальных" 
VV> руководств к "тяжелым" гуевым программам и средам (GNOME, KDE, Mozilla).

Для меня проблема скорее в самой "тяжести" (т.е. архитектурных
ошибках) софта.

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

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

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

apt-get remove им нужен, если честно :)

>> VV> С другой стороны, можно действительно считать, что "документация не
>> VV> продукт, а процесс", и начать с наращивания tips&tricks.
>> 
>> Вроде бы, весь опыт в этом направлении, по большому счету, только
>> негативный. Например, все книжки на букву "Л", не исключая даже Уэлша
>> с Федорчуком.

VV> Надо полагать, что позитивный опыт - в книжках на букву "Ю"?

Книжка на "Ю" пишется в предположении, что у читателя есть доступ к
установленной/администрируемой системе. Поэтому в нем все по порядку.

Книжки на "Л" в массе своей писались в предположении, что у читателя
нет доступа к установленной/администрируемой системе. Поэтому в них
перемешаны главы, образно говоря, про пикап и главы про технику секса.

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

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

Можно возвращаться к канону.

-- 
-- Maksim