[Tutor] Advice required: Documentation Writing / Sofware Testing

[Terry Carroll]

On Thu, 19 Dec 2002, Bob Gailer wrote:

> 1 Use active rather than passive verbs (e.g. "push the button" rather than 
> "the button is pushed")

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.

When I was a computer architect, I would write specifcations that said
something like "... if the operands are equal, bits 34-35 are set to
zeroes."  The thing is, it didn't matter what set those bits: it could be
the Arithmetic Logic Unit, the microcode, the macrocode, an emulattion
layer, whatever.  The only important thing is that the bits got set.  
Saying "... if the operands are equal, the ALU sets bits 34-35 to zeroes"
would have wrongly assigned responsibility for the setting.

I realize this is a pretty specialized area, but as long as we're talking 
about technical writing, I thought I'd bring it up.  I agree with Bob when 
it comes to user documentation, though (and I'm afraid I've already 
deleted the message that started this thread, so he may very well be right 
on the bulls-eye for this thread).

> 4 Be consistent. If you use a certain term to refer to something, always
> use exactly the same term. You are writing a technical document, not a
> novel.
>
> 5 Avoid italics or quotes as the sole attempt to tell the reader that
> this is a new term. Whenever introducing a new term, explain it the
> first time.

I would also say, if you're using some arcane terms, don't be afraid to 
define them multiple times in teh documentation (consistently, of course), 
if the documentation is going to be used as both a reference and tutorial.  
It's kind of maddening to me to look something up in a manual, only to 
find out that understanding the concept I'm lookingup depends on 
specialized definitions, and then having to look them up, and from there 
to more definitions, etc.

Or else, give good examples, so that resort to other parts of the text are 
not necessary.

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.

For example, if you're using Fibonacci numbers as an example of recursion,
don't toss in use of persistent variables as an optimization technique so
that later calls don't have to recurse all the way down (except maybe as a
*second* example, of optimization of recursion).  Just show recursion.

(This is, by the way, my major complaint about the O'Reilley "Programming 
Python" text.  I go to Chapter 6 to understand functions in Python, and 
the author makes me understand about packing first.  I don't care about 
packing.  I care about functions.)

> 8 Different readers have different strategies for searching the index.
> So index things under various headings to make it easy for anyone to
> find what they're looking for. Also include references to chapter and
> section headings in the index. It can be very frustrating to (1) search
> the index, then have to look in the TOC (table of contents) to find the
> term.

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.

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

> 9 Indicate e.g. by bolding the page number(s) in the index that are the 
> main references for a term.

I would also say that the index should indicate where the main reference 
for a term is discussed.  Not that this is different from what Bob said, I 
just think it's important enough to say twice.  :-)


-- 
Terry Carroll        |  
Santa Clara, CA      |   "The parties are advised to chill." 
carroll@tjc.com      |       - Mattel, Inc. v. MCA Records, Inc.,
Modell delendus est  |         no. 98-56577 (9th Cir. July 24, 2002)