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.
Beverly Johnson noted: <<I have never understood why the Technical
Communication community puts the user's needs above our own
convenience in every area except callouts on illustrations. Then the
standard practice is for us to take the easy, less expensive path for
us and usability has to take second place.>>
It's not the standard where we have enough respect from our colleagues
that those who pay the bills actually listen to our advice. We know
there are better ways, but we aren't always given the freedom to use
them.
Richard Lippincott reported one such way: <<An all-too-common way of
indexing the callouts in a figure is to key them to the order that
they appear in the text. For example if it's a disassembly procedure,
the first part removed gets to be #1, the second part removed gets to
be #2, and so forth. This is probably the easiest way for us to write,
because we just keep incrementing the numbers by one as we write the
procedure. The problem is that often this results in the user having
to hunt for index numbers that seem to be scattered randomly around
the illustration... We use index numbers, but run them in order on the
illustration instead of in the text. We put index #1 at roughly the
12:00 position and then run the numbers consecutively and clockwise
around the object. Looking for #17? Oh look, there's #12, so #17 must
be five more ticks clockwise around the circle. Yep!>>
That's an excellent solution, particulary for inventory graphics that
do nothing but show where all the parts are, with no attached
instructions. It also works well for instructions if you don't have
permission to use a better solution: as Richard notes, it makes it
trivially easy for readers to find what you're telling them to look
for, and it's consistent among all photo or illustration series. It's
also easy for translation, and easy for us to write.
What could be improved? The problem with this approach is that it
forces readers to look back and forth between the image and the key/
legend or line in the instructions. Particularly on long pages, this
makes it easy to lose your position in the instructions. A second
problem is that readers must translate between the words and the
number, and then again between the number and the portion of the image
it labels.
There are two improvements on this technique. First, you can sometimes
arrange the callout arrows in such a way that they not only proceed in
a clockwise direction, but also proceed in the same order as the
procedure: step 1 at the top left, step 2 to the right of this, step
three down and to the right, and so on. This can't be done in every
case, but can be done in a surprising number of cases if you have time
to think about positioning of the callouts. I've used it successfully
when I can't use the other solution (below) for any of several
reasons. The better procedure?
Second, you can create one image for each step in the procedure, and
label that directly using arrows, but with the full text provided
beside the image. Think of this as a comic book approach and you'll
get the idea. You can use tables or the "figure plus caption" feature
if your software has more advanced tools. For example, in just about
any word processor or DTP program, you have a table feature. Each step
in the procedure results in two cells in the table: the first cell
contains the full text of the step, including any notes on what to
look for; the second cell contains the actual image, with one or more
arrows pointing at the features of interest that you describe in that
step.
Steps that don't require a graphic get their own row in the table. If
you will only be localizing the instructions in "left to right"
languages, you can also use a two-column table with the instructions
in the left column and images in the right column. That is less useful
for right-to-left languages, because then the image would be seen and
examined before the text that explains what readers should be looking
at and provides context for their task. The two approaches can even be
combined: if you create (say) a 3x3 table with the image in the center
cell, you can run the steps from the top left cell, clockwise around
the table, to the bottom right cell.
I've used all three approaches with considerable success to create
quickstart guides for nontechnical workers, and they loved them. For
online materials, there's just about no downside to this approach. For
printed materials, it's more expensive because of the increased length
of the printed material. But that's often justifiable, particularly if
you're clever about the layout.
------------------------------------------------------------------------
Geoff Hart (www.geoff-hart.com)
ghart -at- videotron -dot- ca / geoffhart -at- mac -dot- com
------------------------------------------------------------------------
Effective Onscreen Editing: http://www.geoff-hart.com/books/eoe/onscreen-book.htm
------------------------------------------------------------------------
Free Software Documentation Project Web Cast: Covers developing Table of
Contents, Context IDs, and Index, as well as Doc-To-Help
2009 tips, tricks, and best practices. http://www.doctohelp.com/SuperPages/Webcasts/
Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! http://www.helpandmanual.com/
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
