Re: Five Point Quality Test

[Ed Blachman x4420 <edb -at- FAIRPORT -dot- HQ -dot- ILEAF -dot- COM>]

I've been following the discussion of manuals intended for programmers
with interest, as I *am* a programmer.  Some of Maria Townsley's
observations apply to me, while others don't....

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

That's only true for me if the manual is *short*.  For anything
sizable, I really appreciate clear, concise layout.  I know that
conciseness and clarity sometimes come into conflict; part of what I
look for in a manual is a good solution to that conflict.

If I'm working in a changing environment, I really want to know what's
changed between versions.  That's an area where sophisticated layout
-- or at least change bars -- can be very helpful.  In a previous job,
I used to receive change packages for looseleaf manuals (the manuals
were published to be put in binders, and updates were published as
sets of replacement pages with change bars).  My boss in that job
insisted on doing some of the replacements himself; it was, he said, a
very efficient way for him to stay up to date on the system even
though he had no time to read through entire manuals.

That kind of stuff is also an important part of the review process.
By the second or third review draft of a manual, I know I don't do as
good a job -- my eyes glaze over at reading it yet again.  Anything
you can do to highlight the changes lightens my burden and makes it
more likely that I'll do as good a job on the nth draft as I did on
the first.

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

That depends.  Very roughly speaking, I use my programmer's references
in two ways.  Sometimes what I want is a detailed explanation of a
particular fine point of the system I'm working with.  In those cases
the intro *should* be skippable, because I will skip it in any case
(see below).  If it says "unlike the rest of this book, the material
in this chapter applies only to one particular flavor of this system"
-- and if I can't easily discover that at the point of reference --
then at best I'll waste some time going down a useless path.  (At
worst I'll build in a bug that won't become apparent until my software
gets to a customer whose flavor is *not* discussed by that particular
chapter.)

Sometimes, however, what I want is a conceptual overview.  How does
the material covered in this chapter fit into the larger system?  What
terms and concepts and data structures does it assume?  Those kinds of
questions are often properly addressed in introductory sections -- or
at least that's where I look for them.  I need that kind of material
just as much as I need fine details when I'm coming cold to a new
system.

>3.  Clearly designed and structured  -  Very important.

Absolutely.

>4.  Index  -  Never use it.  Never will.

Not me!  Indexes -- *good* indexes -- are *very* important to me.
Unfortunately, bad indexes are all too common, because it is both
difficult and expensive to do a good index.  I use indexes most
heavily when I'm looking for detail information (the mode in which I
skip introductory material).  Unless I have a mental picture of where
on the page to look for some detail, or my detail happens to show up
in the table of contents, any other approach takes too long.

-- ed

Ed Blachman     edb -at- ileaf -dot- com   (or)    ...!uunet!leafusa!edb