TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Stuart Burnfield <slb -at- FS -dot- COM -dot- AU> wrote:
> Is a Table of Figures necessary?
> Usually a Table of Contents or Index is meant to help you navigate to
> places of interest in the text -- the TOC to a heading or sub-heading,
> the Index to one or more occurrences of a key word or phrase. When would
> the reader need to look up the name and page number of a screen dump?
> If I left out the Table of Figures, would the reader be worse off? Does
> it matter what the figures are? all screen dumps? all diagrams? some of
> each?
Your question is very timely for me. I just finished writing a section for
our internal styleguide that addresses this very question. I'd love
to hear what others on the list think about it -- I feel I'm flying
in the face of tradition, and so I'm a little unsure about it.
Anyway, here goes:
Composing figure titles
-----------------------
The documentation will have a large number of
figures, many of which will be screenshots. Because
of the number of figures, and because many of the
figures will be small and inconsequential, it is not
necessary to compose a title for each and every figure.
If you provide a title for a figure, the title will appear
in the Table of Figures for the document (similar to a
Table of Contents). Because an extremely long Table of
Figures is difficult to use, avoid naming inconsequential
figures. Do not name very small figures, or figures to
which the reader is unlikely to refer after seeing them
once. Conversely, if a figure provides a large amount of
information, be sure to provide a title for it. Always
provide titles for figures that display analysis results.
Screenshots generally do not require names. The exception
to this rule is the case of a screenshot with considerable
annotation. For example, a screenshot of the entire
application window, in which each part of the window is
annotated with text, should be labeled.
Any figure that contains hotspots (hyperlinking regions)
must have a title. Hotspotted figures are navigational
aids, and the reader should be able to locate them easily
through a Table of Figures.
In summary, do not provide names for
o small figures,
o figures the reader will not use for reference, and
o partial screenshots.
Always provide names for
o figures to which the reader will refer often,
o annotated screenshots,
o any figure with hotspots (hyperlinked regions), and
o any figure that displays analysis results.
You also asked about figure content, so I'll include
another section from our styleguide:
Designing and incorporating screenshots
---------------------------------------
Too many screenshots can make printed documents too long
and can significantly affect the amount of disk space
needed for online documents. To keep the number and size
of screenshots down, avoid taking screenshots of the entire
application or window. Instead, include only the region of
interest, or omit the screenshot altogether and describe it
instead.
The following techniques for minimizing screenshot information
are presented by van der Meij and Carroll (Technical Communication,
Q2, 1995):
"It is often desirable not to give full screen information.
Some manuals give full screen information to support switching
back and forth between manual, keyboard, and screen. The end
result, however, may be that users pay too little attention to
the screen. In minimal manuals, we try to stimulate out-of-the-book
and back into-the-book activities by giving incomplete information.
Full screen information typicaly consists of two types of
information presented in context: a particular content, (e.g.,
icon, warning, question, or menu-option) and some locative
information (e.g., top, bottom, right, or left). Incomplete screen
information can be created by omitting one of the two and by making
information less explicit. For example, stimulating users to attend
to a message of the program can be achieved by statements such as
"A warning appears at the bottom of the screen". Users can be prompted
to locate information with a statement like "Check if the following
sentence appears on your screen: Name Document:..." Another solution
is to show only the important area. Some prompts may even be vague
on content and location to make users depend less on the manual for
support: "Look at the screen to see what further actions you should
perform." "
These comments apply mainly to instructional material, such
as tutorials. However, the concept of minimizing screen information
is valuable in procedural documentation as well. While statements such
as "Look at the screen to see what further actions you should perform"
are obviously inappropriate in a procedural description, it is
appropriate to make a statement such as "Click on the xyz icon
in the QRS toolbox." In the latter case, no screenshot of the
toolbox is needed; rather, a small screenshot showing the icon is all
that is required.
The preceding comments do not apply to drawings. Usually, drawings
illustrate or clarify a concept, whereas a screenshot usually provides
nothing more than a photograph of the graphical user interface.
Do not hesitate to incorporate a drawing in a case where it will
clarify a point that is difficult to explain in words.
--
Glenda Jeffrey Email: jeffrey -at- hks -dot- com
Hibbitt, Karlsson & Sorensen, Inc Phone: 401-727-4200
1080 Main St. Fax: 401-727-4208
Pawtucket, RI 02860
