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.
I'll soon be updating an old help file to conform with the new
shipping version of the software. In the old help, I included images
of the on-screen buttons directly in procedural steps, on the
rationale that "Click [*]" is much more user-friendly than "Click the
button that looks like a squashed bug, a five-legged octopus, or
something like that... anyway, it's at the top left of the screen and
you'll find it if you look long enough". (Note: The icons will appear
as part of a series of steps, rather than as a full-screen
"orientation" screenshot that shows where all the icons are.) The
problem: the icon size almost never corresponds with the text size,
so the line spacing gets weird (or at least inconsistent) in the parts
of the text that contain the icons as inline graphics. It's not a fatal
problem, but it's not very aesthetic either, and it probably adversely
affects readability.
Here are the alternatives I've come up with:
1. Place the icons to the left of the text, label them (e.g., [*]
Octopus button), and say "click the Octopus button" in the text.
That works, but it requires two cognitive steps (first, memorize the
button name and image, then keep this information in mind as you
read the text).
2. Repeat the image of the entire toolbar (or dialog box, or whatever
it is that contains the button icon) beside the step that refers to it
and highlight that button somehow (e.g., with an arrow, with a
callout circle). That takes up an awful lot of screen display, and
doesn't circumvent the problem of having to name "the Octopus
button"; thus, it's really no more effective than alternative 1.
3. Embed icons directly in the text, and accept the funky spacing.
Has anyone come up with a good way to do this without mucking
up the spacing?
Is there a fourth solution that I've simply missed?
