2005-02-24 Ubuntu-doc report

[Matthew Thomas]

On 24 Feb, 2005, at 11:14 PM, Jeff Schering wrote:
> ...
> I would say the number of people who notice when the documentation
> sucks is much closer to 1,000,000 than it is to 100,000. Linux
> documentation has traditionally been poor or non-existant. Most of it
> is written from one programmer to another programmer. However,
> programmers and users think much differently from one another.

Not only that, but people writing Free Software documentation often 
have the wrong idea of when it will be read. As the existence of the 
abbreviation "RTFM" suggests, most people will only read a manual if 
(1) something goes wrong and (2) there is no human available to ask for 
help, because humans are much more context-sensitive (and therefore 
much more helpful) than manuals are.

Much software documentation is of the form "this is what menu item x 
does, and this is what menu item y does, and this is what menu item z 
does ...", which is nearly useless for someone wanting actual help. As 
a result, people have become used to the idea that manuals and 
(especially) online help are next to useless, which is a shame.

-- 
Matthew Thomas
http://mpt.net.nz/