[Techtalk] Re: [Grrltalk] Documentation (was: Mandrake/Linux newbie deep in confusion about apache/advx)

[Alvin Goats]

> I'd like to add something to this: when developers DO try to write
> documentation, they often get criticised for it: "That wasn't easy to
> read!"  "I didn't understand it!"  "How dare you use big words?"
> That doesn't provide much positive reinforcement for continuing to
> write documentation (and getting better at it).
> 

Unfortunately, the developer is also the one who knows the thing best. I
say thing because this applies to electrical engineers, mechanical
engineers, process engineers, design engineers, chemists, physicists,
geologists, programmers, ... the list goes on. 

We are all quite familiar with our subject matter. We, as the
developer/designer/inventor all know the details and inner workings of
the 'thing', but we tend to be very lousy at explaining 'it' to lay men.
That includes telling managers, patent attorneys, line operators, other
engineers, our kids, our spouses, the VP, the CEO, ... , which means
some hardship with work and family. 

I could go into detail about rainbows, index of reflection, refraction,
water vapor and all, but my kids understand "the rain in the air makes
the sunlight make a rainbow". They don't understand water vapor too
well, but they understand rain. 

As such, I *DON'T* have that much sympathy for the developer, I pity the
poor reader. What should be done is to make the developer read someone
else's document/software and decipher it. As the developer goes through
obtuse and undocumented code, the developer will be adding all sorts of
comments as they figure out what was written. Do that a few times and
documenting gets done. Teach the developer how to write simplisticly,
and more people will understand. 

I've seen some of these guys write, and they write to make it as
difficult as possible for others, the idea being to make themselves
"indispensable" and consequently too valuable to be laid off. I was told
this by several engineers and programmers (the authors themselves).
Positive reinforcement after training when the job is done right or at
least better. Negative when the bad practice is continued.

As for newbies and line operators making outbursts complaining of big
unintelligible words, not understanding what was written, documents
written at a Fleish reading level of 23 with a readership of 8: expect
more of the same complaints. Again, I have no sympathy for most
engineers and programmers. When *I* spend 4 hours deciphering a
paragraph, why should I feel sorry for the writer being picked on?

Meredydd's issue with documenting source is a good one. Again, make the
coder decode someone else's obtuse and indecipherable code and they will
gain some practice adding comments. Make it mandatory that code be
commented and enforce the mandate at the work place and in school. 

BTW, Meredydd's code is very well documented, I checked it out. Not for
newbies, but a coder had better be able to figure out what is going on!
Congrats Meredydd!

Alvin