[Techtalk] Re: [Grrltalk] Documentation

[Kai MacTane]

At 10/22/02 05:13 AM , Alvin Goats wrote:

>I've been through some tech writing classes (a physcisit who has to
>write shop processes and procedures for line operators to use for
>assembly, some never finished school, some barely read, and some that
>english is not their first language). The main thing is to use simple
>words as much as possible, write at a third grade reading level (this is
>the most understandable level by everyone, and not an insult to anyone).
>Write in first person, active voice (you have to do this first...) not
>third person passive (ideally, one should do some of the actions in a
>serial fashion...).

Nitpick/clarification: "You have to do such-and-so" is *second* person. 
First person is: "It was a quiet night in the city when the dame walked 
into my office..."

But I do agree with the advice to write in second person, active voice.

                                                 --Kai MacTane
----------------------------------------------------------------------
"When nothing's sacred any more,
  When the demon's knocking on your door,
  You're still staring down at the floor."
                                                 --The Chameleons UK,
                                                  "Swamp Thing"