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.
Earlier this week, I introduced the problem of including icons in
help files in the form of bitmaps, despite the problematic line spacing this
caused, and introduced three alternatives: place the labeled icons in the
margin as ?reminders? and then refer to them using those labels; repeat
the entire toolbar (or whatever) graphic, but highlight the icon being
discussed; and embed icons directly in the text, and accept the funky
spacing. I didn?t suggest resizing the icon bitmaps themselves, since
we?ve seen plenty of discussion on techwr-l about the problems and the
extra work that this entails, but I suppose it?s another option. I got the
following suggestions:
Nobody voted for repeating the whole image and highlighting the
icons. Embedding the icons directly in the text works best if you?re
prepared to define a line spacing adequate to leave room for the icons;
this is most likely to succeed with short, single-line steps, but should be
an adequate solution even for longer steps. If the icons always (or
generally) appear in the first line of each step, then playing with the
?space before? setting of the paragraph?s style can minimize the problem.
If you want the icons to go in the left margin, Doc-to-Help lets you insert
?margin notes? effectively. With other software, a table might
accomplish the same result (just like using tables to structure your layout
in HTML); it?s probably much easier to just set the icon flush left and
indent the remaining lines of the steps so the text ?wraps? around the
icon.
Thinking a little further outside the box, Sharon Burton-Hardin
proposed using ?popups? so you can use the text label within the text,
while still providing a direct one-click link to the image for those who
need the reminder. Laurel Nelson suggested that (if the software
supports this), it might be more effective to simply refer to the keystroke
equivalents for each icon (e.g., the function keys or alt-key
combinations), and let those who love icons learn the icons on their own.
This makes sense given that the current trend in minimalist
documentation seems to be to explain only one way to accomplish a
goal, and let users discover others on their own. I?d accept that as a
helpful solution if it?s accompanied by help text that specifically explains
that there?s more than one way to do something, and then provides a list
of the alternatives.
Thanks to Sam Beard, Sharon Burton-Hardin, Virginia Day, David
Knopf, Laurel Nelson, and Paul Strasser for their suggestions.
