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.
Subject:Table of Figures -- the envelope, please... From:Stuart Burnfield <slb -at- FS -dot- COM -dot- AU> Date:Mon, 18 Sep 1995 15:19:46 +0800
There were many good responses to my question about Tables of Figures.
In particular, Glenda Jeffrey <jeffrey -at- lemond -dot- hks -dot- com> posted a fine
excerpt from her Style Guide. It covers when to provide a TOF, when to
caption figures, how to cut down on the size and number of screen
shots, and more. It's great -- get a copy from me or from Glenda.
I've included a brief summary of the other replies below. I edited
most messages somewhat -- hope that's OK. Note: Ellipses=snipsies.)
I decided to take out our TOFs. We have many screen shots, few diagrams.
IMO the screen shots are more useful for context than for navigation.
When we add more diagrams I expect to put these in a TOF.
Thanks for all your thoughtful replies.
Is a Table of Figures necessary?
-------------------------------- --------------------------- YES
(john -dot- blair -at- nb -dot- rockwell -dot- com): "... The reader may only need to reference
a particular table or figure (even if it is a screen dump to compare what
"is" and what the document suggests "should be") and the TOC would be a
logical place to go to find the page reference."
John also suggested not giving lists and figures a separate heading...
Just use "Figures" and "Tables" as headers in the overall TOC."
(radomski -at- pubs16 -dot- si -dot- com (Stan Radomski)): "...figures and the tables
convey a lot more information for that amount of space involved than most
text does. After I have become familiar with the information in a book,
I usually only have to refer to figures or tables after a while..."
(Howard Gold howardg -at- savvy -dot- com): "... If the dumps show screens offering
the reader instruction or reference, the reader may want to see that on
paper... if the reader thinks of a process graphically, they may want to
look up the graphic presentation before looking at our perfectly
grammatical, clear, and clever instructions."
(paul -dot- cheverie -at- GPO -dot- CANADA -dot- CDEV -dot- COM): "Listing the figures and tables
within the TOC just makes them easier to find. IMHO there are three
things that a technical manual must be:
- it must be easy to use.
- it must be accurate
- it must provide complete information (to the level it is written to)."
(Louise Mayberry <LOUISEM -at- cronus -dot- aiinet -dot- com>): "Many users need to refer
to the manual to check what their screen shows versus what it should show."
(twt -at- cei -dot- net (Tommy Trussell)) got flamed at an STC seminar for suggesting
it, the reasons apparently being:
- we've always used them before
- engineers who are especially visually oriented will turn to the TOF first
(Jim Grey <jimgrey -at- IQUEST -dot- NET>):
- is yet to see a useful Table of Figures
- surveyed his users... none reported ever using the TOF or Table of Tables
- his company's biggest customer went ballistic -- thought it was possibile
that one of their users *might* want the TOF -- made them put it back
("Sue Heim" SUE -at- ris -dot- risinc -dot- com): "Depends on the document and your target
market. If your figures are illustrations (not screen grabs), then maybe,
especially if your market is very technical." Summary: for software and
hardware user documentation, no. For a field service manual (or a very
technical hardware manual), perhaps.
(mpackman -at- lint -dot- cisco -dot- com): finds that many people, especially engineers,
would rather search through a table of contents/figures/tables. She
suggests the most likely use for a TOF is where you're looking at a
screen with a field or counter you don't understand -- you might look
up the TOF to find where in the manual that counter is explained.
(khenry -at- austin -dot- asc -dot- slb -dot- com (Katie Henry x3432)): only uses figures if:
- the user would look it up independently of the text (e.g. block diagram)
- it's a figure that will be cross-referenced in several places
- it needs a title to describe what it is.
"In practice, my software manuals have almost no figure titles and I
usually don't bother with the list of figs... My hardware manuals are
full of fig titles..."
(Millman_Harvey millman -at- jmbcorp -dot- mhs -dot- compuserve -dot- com): "If the screen dump
is useful without its supporting text, or if the reader needs to see an
example of a given screen, then perhaps a TOF will help them find it."
(Becca Price ncr02!ncr02!mdelaney -at- UCS01 -dot- ATTMAIL -dot- COM): "only if there are
key or important things that someone might want to refer to and would
need help finding the illustration. this only works if the illos are
well named, however."