TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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.:)
-maria
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
