Re: Five Point Quality Test

Subject: Re: Five Point Quality Test
From: Len Olszewski <saslpo -at- UNX -dot- SAS -dot- COM>
Date: Wed, 7 Jul 1993 10:57:17 -0500

Maria Townsley and John Sanders discuss programmers as a primary
audience for a manual:

> >from Maria Townsley:


> >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
> of the set of programmers. Hey, software engineers are people, too!


You know, it's interesting, people become conditioned by what they
usually see. I've had programmers suggest converting entire drafts into
the passive voice in technical review, obviously because this is what
they were accustomed to seeing. The idea is that since most of the
manuals and textbooks *they've* read are awkwardly worded and full of
arcane constructions, well, oughtn't the manual that documents their
work also be like that? Wouldn't *that* make their software seem,
somehow, more "credible"?

Now, if the programmers happen to be your primary audience, you could
give them what they *expect*, and argue that this is what they *want*.
However, if you give them something of a high quality that meets their
needs, I doubt you'd hear many complaints regardless of their

A lot of programmers use manuals as a last resort (similar to many tech
writers I know), and anecdotal evidence to the contrary, have *no one
way* they find information in a book - more or less like the general
public, but a bit more sophisticated. Manuals with multiple entry points
do well with sophisticated audiences, especially books that scan well,
so the advanced readers know where to look for the *meat*, and can skip
completely over the "fluff". Also, they can easily (if sheepishly)
*return* to the fluff, though I know that rarely happens 8-).

> >4. Index - Never use it. Never will. If they can't find something

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

My own comment regarding technical books without indexes: don't! If
some people never use them, ok - give a bunch of other ways to find the
info (running heads, alphabetical book structure, margin tags, icons or
images, sophisticated toc's, head levels with banners, etc.). However,
unless contrained by budget, style guide, editor or company policy,
never penalize the folks who *do* use your indexes. And there are more
of them than you think (even a couple of programmers, I'll wager).

Ok, somebody else can take a turn now.

|Len Olszewski, Technical Writer | "If the shoe fits, it's ugly." |
|saslpo -at- unx -dot- sas -dot- com|Cary, NC, USA| - Gold's Law |
| Opinions this ludicrous are mine. Reasonable opinions will cost you.|

Previous by Author: Papers from Proceedings
Next by Author: Re: Five Point Quality Test
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