answers Re: Linux is not for consumers!

[Alvin Oga <aoga@ns.Linux-Consulting.com>]

On Thu, 11 Dec 2003, Richard Kimber wrote:

> On Thu, 11 Dec 2003 18:01:44 +0000
> Colin Watson <cjwatson@debian.org> wrote:
> 
> > > This may be true of some; but even reasonably intelligent users with
> > > quite a lot of experience can come unstuck in those areas with which
> > > they are not familiar, simply because the documentation is often so
> > > poor.
> > 
> > In many cases it will remain poor until people report what they found
> > confusing about it - it's sometimes hard to document something you wrote
> > in a way that somebody unfamiliar with it can understand.
> 
> People do. Their confusion is evident in the posts to mailing lists for
> each app.  Often questions go unanswered.  It may be, of course, that the

or the questions receive multiple answers ... of varying degree of
completeness ... and all based on some [un-posted] assumptions

and even some un-related answers :-)

usually, 95% of the time, the answers is already in the FAQ and HowTos
	- whether its well written and easily understood is a separate
	problem

breaking the "old style" manpages and adding some examples would improve
significantly improve the value of "documentation" ..
	- notice that most all faqs and howto has "examples"

	- i'm one of those that thing "rtfm" ( ie man pages ) think
	that is a poor answer ... or a non-answer, but hopefully
	they read the man pages and still confused

	- ever read the man pages for bash ?
	for simple scripting problems:  echo "today's date is: `date`"

c ya
alvin

> documentation people are silently perfecting their document taking these
> questions into account, but in the meantime people are confused.  This is
> not true of all apps.  Some are done very well indeed and the developers
> interact with users very well.  But it is true of enough important areas
> (e.g. sound) that the original thesis of this thread is true.
> 
> And there are some cases where it's hard to know what to say. What, that's
> constructive, does one say about the manpage for gnome-alsamixer
> (0.9.3-3)?
> 
> - Richard