[docs] Re: mozilla.ru

[Vadim Vinichenko]

aen пишет:

<skipped/>

> Мне хотелось бы теперь плавно закруглить тему, которую поднял Rider, тем 
> более, что мы с ним сейчас ее обсудили в офисе.
> На самом деле, речь идет не о вытеснении "консольных" приложений из  
> user, а о плохом качестве документации по KDE и GNOME. Rider считает, 
> что они для домохозяет, мне же кажется, что они просто ни для кого.  И 
> именно их надо  -- переделывать, а, может быть, просто выкидывать.
> Каким должно быть руководство по пользовательсскому интерфейсу для 
> _наших_ пользователей, среди которых нет домохозяек (не в смысле рода 
> занятий, а в том смысле, который обычно вкладывают в это понятие)?
> Я не готов сейчас дать ответ, но могу привести  в качестве примера 
> статью Вадима про новое в mozilla-1.3. Есть и второй пример, -- лекции, 
> автором которых являестя участник этого списка, но они еще не опубликованы.
> Видимо, надо описывать характерные приемы и особенности работы с 
> интерфейсом, а не то, что и так интуитивно ясно или быстро становится 
> ясно. Возможно, надо просто задаться целью собрать tips&tricks, а 
> дальше, если будут время/силы нарастить мясо на этот костяк, но не 
> слишком много.
> В такую пользовательскую документацию руководства по bash, vim etc. 
> войдут органичнее.
> 

То есть, как сказали бы на телевидении, нужны "смена формата" и 
"изменение принципов программирования". Мысль, безусловно, любопытная и 
актуальная:-)

Традиционный подход к документированию "программных продуктов" часто 
выглядит примерно следующим образом. Составляется одно из двух или оба 
вместе:

* User Guide, написанный в (как правило, фантастическом) предположении, 
что пользователь, последовательно читает его, сидя перед программой и 
последовательно овладевая ее функциями, от простейших до самых сложных;

* Reference Manual, справочник, претендующий на всеохватность и 
освещающий в равной степени вещи очевидные и тривиальные и совсем 
нетривиальные.

Если дойдут руки, к этому может быть приложен Quick Starter Guide, а уж 
когда отстрелялись по этим мишеням, можно добавлять всякие "Приемы 
эффективного использования..." и т.п., до которых руки, как правило, не 
доходят, а умник еще и скажет, что это такая "экосистема" в отрасли - 
"Приемы..." оставлены независимым авторам (или отдельному корпоративному 
издательству:-).

Сей канон нам заклеймить нетрудно:-) - большинство информации никогда не 
бывает востребовано и "загораживает" доступ к информации действительно 
нужной. И соблюдать каноны мы здесь никому не должны.

Вопрос вот какой - есть ли "культурные образцы", позитивные примеры 
альтернативных практик, не просто в форме книг или статей, а именно в 
форме документации, прилагаемой к продукту?

С другой стороны, можно действительно считать, что "документация не 
продукт, а процесс", и начать с наращивания tips&tricks. На каком-то 
этапе надо будет хотя бы приблизительно обрисовать портрет пользователя, 
которому обрисована эта документация, а также сформулировать цели 
документации - какие-то шаги к тому и другому здесь уже сделаны.

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