[Tutor] Advice required: Documentation Writing / Sofware Testing

[Bob Gailer]

At 11:35 AM 12/20/2002 -0800, Terry Carroll wrote:
>I'm a big fan of active voice in ordinary writing, but in some technical
>contexts (in particular, specifications), passive voice is the right way 
>to go.

I agree. I was reacting, in part, to Memorex's guidelines insisting that 
operator instructions be passive.

>By the way, on examples: make them examples of as little as possible,
>restricting their scope to the thing being explained.  It's kind of
>frustrating to look up the description of function X, only to find that
>the example needlessly requires that the reader also has to understand
>functions Y and Z.

Yeah, and I've seen this in other Python books. A chapter on database 
interaction had an example whose major focus was the soundex algorithm, and 
had (as I recall) one SQL Insert and one SQL Select statement. I had to 
wade thru a lot of stuff to find the SQL.

>The index should also be prepared by at least one person who is not the
>author, and who can bring a fresh perspective to the organization --
>because that's what your reader is going to have.

It's good to also have a member of the target audience review the document. 
I was once asked to review a course in IBM's MVS JCL. I said "I can't do 
that; I don't know JCL." At which point the response was "That's exactly 
what we're looking for." (Unfortunately, as I waded thru the course my one 
consistent and never answered question was WHY JCL in the first place when 
there are much easier ways???)

>Also, consider indexing a subject, not only under the term you use, but
>also under the term someone who doesn't yet know your terminology mught
>use.  For example, if you have a function trim() that removes blanks,
>consider "stripping blanks: see trim()."  If you have a command FIND that
>finds a string in a piece of text, consider "locating a string: see FIND".
>
>This is especially important when you can't know what to look under unless
>you already know the answer you're looking up.  If my question is "how do
>I specify formatting a string," I want to be able to look up "format" or
>"string", not "%s".

YES YES.

Bob Gailer
mailto:ramrom@earthling.net
303 442 2625