Figures: using the title "Figure x" in documentation

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Claire Philpott provides more details: <<my query regards the captioning
with Fig 1.x screen captures in the User Manual... The manual contains more
or less one screen shot per page with explanatory text, field descriptions
and steps to complete user tasks within the screen shown... as this is new
software we have no users to refer to for preference. However we do know
that  the main target audience is not technical and will use the manual in
order to learn how to complete set tasks within the system.>>

Although the use of "as shown in Figure 1" seems quite rare in software
documentation, the absence of this practice does not mean that omitting such
labels is a good thing. I come from the world of scientific publishing, in
which it's rare to refer to a graphic other than by its Figure number, and I
have found this approach to be a godsend both as a reader and as a
writer-editor: it neatly resolves the problem of occasionally convoluted
cross-references such as "see the figure on page 17 midway between the
second figure from the top left and the fourth figure on the right", and if
you're moving the information online, it allows for really easy hyperlinking
simply by adding a bookmark named "Figure X" for each figure (using the
number provides a consistent, easy to remember naming system).

The fact that there's generally only one figure per page in your material
might suggest that adding a caption and number is unnecessary, but the more
I think about it, the less I believe that omitting them really helps
readers. As far as the difficulty of using this system, I can only report my
own experience: I immediately understood "see Figure 1" the first time I
encountered it in a journal article, whereas I sometimes find unlabeled
screenshots difficult to relate to the text that describes them. (In part
because of poor layout, but mainly because reference to the figure is left
implicit rather than made explicit.)

So all that being said, my response comes down to "why not try using the
figure captions?" It's vary unlikely to harm comprehension*, quite likely to
improve it, and the fact that it looks different from standard practice is
rarely a good reason not to try it.

* I'm assuming a reasonably literate audience here. An audience with a large
component of ESL or low-literacy readers might have more trouble with the
system. Using "Screenshot 1" or "Picture 1" would probably resolve that,
even though it looks and feels really weird to me, having been conditioned
by now to look for Figures.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html

"How are SF writers like technical writers? Well, we both write about the
things we imagine will happen in the future!"--Sue Gallagher

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Develop HTML-Based Help with Macromedia Dreamweaver 4 ($100 STC Discount)
**New Dates!!** San Francisco (Apr 16-17), San Jose (Mar 29-30)
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.

IPCC 01, the IEEE International Professional Communication Conference,
October 24-27, 2001 at historic La Fonda in Santa Fe, New Mexico, USA.
CALL FOR PAPERS OPEN UNTIL MARCH 15.  http://ieeepcs.org/2001/

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.