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.
Michelle Vina-Baltsas wondered <<How do you all reference
screen captures in your help files?>>
It's generally wisest to avoid "shown below" and other positional
references because you can't always be sure where the graphic will
appear; the most obvious example is a graphic that appears
outside the portion of the file that can currently fit in the window.
Moreover, if someone takes your file and repurposes it, they may
also do some reformatting and all the "belows" suddenly become
"above" or "at left" or a random combination of various other options
that some poor editor has to track down and correct.
The simplest and safest way to do such references is using the
traditional technique of call-outs: the text that says "enter your
name here" points directly at the Name field and connects to that
field with an arrow. I'm not sure how you could implement this in a
typical help file without incorporating the text within the screenshot
(i.e., as part of a single, composite graphic). Thus, a better
approach might be to simply snip out the relevant portion of the
graphic and use it as a smaller, inline graphic tied to the line that
references it. I've used that approach with moderate success for
buttons and toolbar icons. For example:
Enter your name here: Name [ ]
(Imagine that everything before the colon is text, and everything
after it is graphical.)
If this is contextual help, the description will generally appear near
the field you're referring to (since the most probable reason the help
appears on-screen at all is because the user invoked it to explain
the set of fields currently on the screen). Readers can then find the
field easily enough by glancing at the application window. If you
suspect that readers may reach this part of the help file by
browsing (i.e., so that the field being described isn't on the screen),
then you can always provide a single larger graphic in the form of a
popup: the help topic's title appears beside a tiny thumbnail of the
dialog box (say about half an inch on a side), accompanied by the
text "click here to see the entire dialog box and an explanation of
how to reach it from within your software".
<<Also, for those of you who add hotspots to your screen
captures, how do you reference them in your help file?>>
With a simple statement: "Click this button [in a screenshot of the
icons or button] to jump to the portion of the help file that describes
it." Modify the wording as required to suit your specific context.
