Baslinux mailing list

[James Miller <jamtat AT mailsnare.net>]

On Wed, Jan 10, 2007 at 06:37:24PM +1030, Greg Mayman wrote:
> 
> Too many bosses in charge of development companies think that
> someone who knows the work can write it up -- wrong! The article
> quoted a paragraph from a description of a metalurgical process,
> written by the scientist who developed it, that was about 200
> words long, and apart from not making grammatical sense it was
> quite obscure to people in the field who tried to read it.

This is exactly the problem with alot of Linux documentation--especially man 
pages--though 
the boss part of the equation is missing. Developers and programmers write 
documentation 
because Linux is a volunteer enterprise and it falls by lot to them. In my 
experience, about 
5% of it is well written and understandable, often even by newbie-types. The 
other 95% 
ranges from difficult to downright impenetrable (try reading the man page for 
psnup some 
time). That writers for that 95% are alot like the scientist you're talking 
about: they're 
really the last people who should be writing the documentation. They should 
play a key role 
of course, but they are often incapable of providing an overview of their 
program because 
they are so deeply entrenched in the technical details of the program and 
programming it. 
There really needs to be a group of writers not so bogged down in technical 
detail to scour 
and rewrite this documentation.

> Then there are the other bosses who give the job to an ordinary
> writer, who will tend to change the wording to make it "more
> interesting", and you get the kind of jazzy, catchy, and often
> inaccurate stuff you see all too often in advertising blurbs.

Linux documentation hasn't gotten to this stage yet, so far as I can tell.

> The biggest problem that is causing the most frustration is that
> I don't know enough yet to be able to frame many questions.

I'm very familiar with this situation. I was in myself not so long ago. 
Sometimes, I'm not 
so sure I've even made it out yet :)

James