<<< Date Index >>>     <<< Thread Index >>>

Re: Searching in the index is not documented



On Thu, Aug 17, 2006 at 12:29:49PM EDT, Rado S wrote:
> =- Alan Mackenzie wrote on Thu 17.Aug'06 at 16:14:08 +0100 -=
> 
> > As a beginner, I didn't know where to look. Despite searching
> > long and hard in the manual for the answers to these questions,
> > I didn't find them. {...}
> > Hence, I'm suggesting to the Mutt team, in a respectful fashion,
> > that it could be helpful to enhance the manual.
> 
> Good docs are generally underappreciated to work on.
> Working on documentation is not rewarding (enough) for coders, they
> prefer to work on technical/ functional improvement rather than
> docs. As long as there are such things to fix, this won't change,
> and there is a lot of technical stuff to fix for mutt.
>  That's because unlike improving code -- where you immediately see
> the technical benefit when the changes work and people who asked for
> it to be implemented report back -- improved docs go unnoticed since
> you hardly can see a benefit there: if it helped, people are happy
> but quiet about it.

not necessarily .. the returns in terms of customer satisfaction and a
marked decrease of the volume of pointless calls to tech support can be
quite significant. 

.. not sure how this transposes to the gnu/linux world, though.

>  Coders more easily see the need to improve code than docs, since
> they use the code themselves, but they know their stuff so don't
> need any docs at all. 

Not entirely.  When problems surface there are cases where problems are
easier to address when you are dealing with an informed user base.

> As long as the stuff is _somehow_ documented,
> all is fine for them. Plus, it takes _a lot_ more time to improve
> whole docs than a small piece of code.

That's why GUI's usually come without those fat manuals .. Since
everything is perfectly intuitive, it's totally unnecessary ..  Time is
money.
> 
> There are a few who'd be willing to work on it (incl. myself), but
> there are various reasons why this hasn't happened yet (and maybe
> never will).  However, the hope that appreciation of usefulness of
> docs will increase dies last. ;)
> 
> > I would have found it useful to have read this explicitly in the
> > manual 2 months ago.
> 
> As mentioned, with the current manual you _could have_ found it if you
> had read it completely and remembered all interdependencies.
> 
Thanks.  That's pretty much what I meant when I wrote "Reference Guide".

A bit like trying to learn a foreign language by reading its dictionary
from cover to cover..?

Thanks

cga