Baslinux mailing list

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

On Tue, 9 Jan 2007 03:32:28 +0000 (UTC), sindi keesan wrote:

>> Don't tell me about documentation. I spent about 30+ years
>> modifying, or designing and building electronic hardware and
>> writing up documentation for the work I did. And I very quickly
>> found that good documenation usually takes many times longer than
>> the work that it was done for.

> You are obviously the best qualified to write up documentation for BL3
> from the aspect of a newbie, as you learn it.

Hmmm... it's a thought. I'll do what I can as I have time. But I
can't promise anything.

I never was very good at writing the stuff up by myself. I always
explained it to someone else while they took notes, then they
brought it back to me to correct any inaccuracies.

And these days my brain isn't as agile as it used to be <GGGG>

> My partner spent 20 years writing up his own 4K text editor in Assembler
> language and the documentation is about 20 words.  He does not write well,
> nor do some other programmers.

Yes, I do know that (see above).

There was an article (I can't remember now where I saw it) about
technical writing and how it was really a field of its own.

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.

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.

> All I resent is your attitude.  And the fact that you are not bothering to
> search the archives for answers before posting your questions, many of
> which have been asked numerous times before.

I looked at the archive.... sheesh! it's really daunting!
Searching by subject is one thing, but I don't even know what
subject to look for for most of the stuff.

But it will be a lot easier now with that google "script' of
Steven's.

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

> There are several groups for new linux users which you could find via a
> search.  I think Steven linked to one or more in the links home page.
> I got help from one when this list could not solve problems for me.

I'll look for them.

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