Baslinux mailing list

["Greg Mayman" <gmone AT tpg.com.au>]

On Wed, 10 Jan 2007 07:38:28 -0600, James Miller wrote:

> 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).

And I fall in that 95%. But I have encouraged myself to go back
and reread what I have written, to see whether there is any way
it could be MIS-understood. If there is, then it needs rewording.

Unfortunately that practice is not followed by most people these
days, including professionals. Two examples of signs that I have seen
recently, with the literal translation of what they are saying:

"Stairs must be used when escalator is stationary" (someone has to
stay there and keep using the stairs until the escalator is
restarted or someone else comes to relieve them)

"Stand behind white line until the train has passed" (wait there
for hours if necessary until a train comes along...)

Of course in those cases it is fairly obvious what they meant to
say: don't walk on the escalator when it is stationary, and don't
cross in front of an oncoming train.

But I digress....

Thanks for your help. I shall wait for the Running Linux book to
arrive, and just "dabble" a little with BL until then.

As for writing the New Users HOWTO.... well, we shall see.


.   ,-./\
.  /     \     from Greg Mayman, in Adelaide, South Australia
.  \_,-*_/     "Queen City of The South"    34:55 S  138:36 E
.       v