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