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:sanders_j -at- TBOSCH -dot- DNET -dot- GE -dot- COM Date:Wed, 7 Jul 1993 09:17:26 EDT
Hi All,
>from Maria Townsley:
>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.
While I know some programmers like this, I still think this is a jaundiced view
of the set of programmers. Hey, software engineers are people, too! I think they
deserve a manual that's clear, graphically astute (diagrams, flow charts, even
diagrams of system interactions), and built with the same quality as other
manuals. Some of what I refered to is user documentation, but I also wrote and
reviewed system management documentation. Have you ever seen the Unix document
set? For most systems/flavours, this means documentation that was written for
people who already know what they're doing, and know where to find it.
>4. Index - Never use it. Never will. If they can't find something because
I hate this, especially in a programmer-oriented manual. I can understand why
in-house documentation might lack this, but not for a professional manual.
Nothing is more obnoxious than not being able to find something, and I do know
programmers who use indexes and complain when they're poorly done or not even
there.
BTW, not documenting code seems to be a long-standing trend in software, but I
have seen the edges start to erode. And the attitude that it should be
instantly apparent from the code is assinine. I've seen programmers struggle to
figure out what's going on in their own code.
It sounds like you have a fun job. Maybe your co-workers need some technical
communication classes? I always found it funny how someone who refused to
document his code could turn around and complain about the documentation he
had to use. Programming is no longer a white-tower, high temple activity left
to only the high gurus.
Right, that's enough blasting randomly into the ether.
