Re: Figures - Captions and References?

[Todd Snarr <todd_snarr -at- AUTOSOFT -dot- COM>]

Eric Dunn writes:

>When looking for an illustration in a manual (paper) which would you
rather
>scan for? A simple number or a caption that might possibly contain
>technical terms that you are not yet familiar with? While we can
>dynamically link references which is more elegant in a paragraph?
>
>1. refer to Figure 15
>or
>2. refer to "Widget Disassembly" on page 55

I think it probably depends on the audience and the purpose of the
communication. Around here we use figure numbers and captions in our
DEVELOPMENT and engineering source documents (proposals, functional specs,
design docs, testing plans, reports, technical briefs, and so forth).
Engineers and clients like to see a certain level of "formality" in the
development effort. If I'm a software engineer, I may need to find a
particular window, dialog box, or illustration. Figure numbers and a table
of figures in this case really helps. "Lets see, what's the name of that
function on the Widget Disassembly dialog box again?" "How does the Widget
Disassembly dialog box compare with the Widget Assembly dialog box?" (They
should probably have the same look and feel, don't you think, Dilbert?) For
the most part, readers of these documents are reading to learn (check or
reference) as opposed to reading to DO. Since these documents are often
organized around the system, numbering is helpful (particularly if the
system is poorly designed).

However, in EDUCATIONAL documents (user guides, training guides, marketing
materials, and so forth), I don't think figure numbers are as critical
(IMHO). And in these documents, I'd use callouts instead of captions. If
I'm using a software application, I typically turn to the manual to get
something DONE or to perform a particular task.

>If you prefer #2, think of what happens when your figure reference is in
>another section. "refer to "Widget Disassembly" on page 55, section 6"
>instead of "refer to Figure 6-23".

I'm not sure I prefer 1 or 2 in an end-user document (I'd prefer #1 in a
development document). If I'm using a "task-oriented" manual--a manual
that's organized around what I need to DO (as opposed to around the
system)--I'd probably prefer to see a reference like "see Disassemling
Widgets." I don't care what the figure in that section is called or how its
numbered. I just want to know how to disassemble widgets!

>If you have two figures on a page you are starting to ask your reader to
>memorise a lot of information (need to know name +page). Figure numbering
I
>would say is nearly always an added aid to the reader and in some cases
>absolutely indispensable. Everything possible should be done to aid the
>reader to maintain their train of thought. It is not a formality to number
>the figures. It becomes consideration for the reader and makes our
>references shorter.

Again, I think it depends...and yes, I do think numbering is a "formality."
In a task-oriented document for a software application, simply put the r
elated dialog box after the associated step in the process. If I numbered
every single dialog box or window in some of my user guides, I'd have 500
figure numbers. This would be distracting.  I was an STC judge this past go
around, and I can't recall any figures that were numbered in the
"task-oriented" manuals that I judged. I take that back...one entry
numbered some figures, but not others (oops). And I can't recall any of the
other judges in my group caring that figures weren't numbered in these
procedural documents. (They did care about inconsistencies and how well
these figures were integrated, however.)

>Also in the mauals we produce we nearly always include the figure number
>reference in the title (i.e: "2.1.3   Widget Removal (Figure 2-22)").
>Without numbering what are you to do? I know we aren't the only ones doing
>it this way.

Well, If you're that determined on having your user see Figure "2.1.3
 Widget Removal," tell them to turn to the "Removing Widgets" topic. Enough
said. If there's a drawing or illustration that you absolutely want them to
see, say something like "For a description of XYZ, see the following
illustration."

>On a similar note, this is a thing that makes me detest most On-Line help
>systems. No page numbering. You have to remember an entire series of
clicks
>and links to get to information you know is in there. You can't tell
>someone goto page 66 it's all explained there. Often it seems on-line help
>was produced because the writers could not come up with a logical way of
>explaining their product. So instead of ordering it logically, they took
>the manual, split it into a million pieces, and cross-referenced (many of
>them circular) the whole lot.

Ouch...now your talking about another beast entirely. Why do you want page
numbering in online Help? When using online Help, why do you need to
remember "an entire series of clicks and links" to get the information you
need? You're right...another topic entirely. I will say that good online
Help systems that I've seen are organized around tasks (and also have good
reference topics as well). I think if you were to use a good online Help
system designed around what you need to do (not around a print manual or
the system), then you'd have a different experience.

Todd Snarr
Sr. Technical Writer
Auto-Soft Corporation
5245 Yeager Road
Salt Lake City, UT  84116
todd_snarr -at- autosoft -dot- com


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=