Skip to Content.
Sympa Menu

baslinux - Re: [BL] Help for a newbie

baslinux AT lists.ibiblio.org

Subject: Baslinux mailing list

List archive

Chronological Thread  
  • From: James Miller <jamtat AT mailsnare.net>
  • To: baslinux AT lists.ibiblio.org
  • Subject: Re: [BL] Help for a newbie
  • Date: Wed, 10 Jan 2007 07:38:28 -0600

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




Archive powered by MHonArc 2.6.24.

Top of Page