Re: Five Point Quality Test

Subject: Re: Five Point Quality Test
From: Maria Townsley <maria -at- MSD -dot- MEASUREX -dot- COM>
Date: Wed, 7 Jul 1993 08:46:26 -0400

Hi John.

I agree with most of your statements. However, I write the entire
documentation set aimed at a variety of audiences. Your description probably
fits the user documentation. Programmers are are separate breed. Most things
that are important to the user are considered "fluff" to the programmer.

1. Appearance - It's nice if the manual looks pretty, but single-spaced
pages loaded with straight text is fine too.

2. Introduction/Startup stuff - Those are the pages you skip over to get
to the real stuff.

3. Clearly designed and structured - Very important. See 4.

4. Index - Never use it. Never will. If they can't find something because
the manual was not clearly designed and structured, they'll call and ask me
where it is. Even if I walk them through looking it up in the index and
turning to the right page, they will show no sense of embarrassment. I
think this might be an extension of the programmer logic that programs do
not need to be documented. This is stated simply as "If you can't read
the code, you don't belong here."

5. Complete and informative - I write in a development environment. The
language and tools are also evolving. The programmers are often using
the tools in ways that our tool developers didn't anticipate and I didn't
document. Programmers somehow expect though, that if they thought of it
this morning, it should be in there when they look. If it isn't, they
call and tell me. They seem to think that the revision process goes
something like:

1 - I thought it might be possible to do this.
2 - Because I thought of it, it must be in the manual. Look in the manual.
3 - Why isn't the specific example that I thought of in the manual?
4 - Call Maria.
5 - Next time I look, it will be there.

This is the correct order. The problem is, they expect all five steps to
happen within a single afternoon. Oh well. At least I have them trained
to tell me when there is something that they think belongs in the manual.:)

Domain: maria -at- msd -dot- measurex -dot- com Maria Townsley Technical Writer
UUCP: ...uunet!mxmsd!maria Measurex
Management Systems Division
Voice: (513)-825-3931 x-316 1280 Kemper Meadow Drive
Fax: (513)-825-5393 Cincinnati, Ohio 45240

Previous by Author: job - part-time wr. - Milford, OH
Next by Author: job information
Previous by Thread: Five Point Quality Test
Next by Thread: Re: Five Point Quality Test

What this post helpful? Share it with friends and colleagues:

Sponsored Ads