Re: Five Point Quality Test

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.

-John Sanders-


Previous by Author: Five Point Quality Test
Next by Author: Re: Should STC be on this list? Yes.
Previous by Thread: Re: Five Point Quality Test
Next by Thread: Re: Five Point Quality Test


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


Sponsored Ads