Style for hyperlinks?

["Geoff Hart" <Geoff-h -at- mtl -dot- feric -dot- ca>]

Karen Casemier is <<...now documenting an application 
which uses links instead of buttons to open dialog boxes. 
These appear just like HTML links... I'm wondering how to 
reference them in the documentation...>>

The rule of thumb is to make textual items resemble their 
appearance on-screen as closely as possible in the 
documentation. Since the type of hyperlinks you're 
documenting are pure text, you should underline them so that 
they appear identical to the way they appear in the 
application. So I'd write something like:
	Click the _hyperlink_ link to do X.
(where the underscores indicate that the word they surround 
is to be underlined).

This gets a bit trickier when you're dealing with screen items 
that are more clearly graphical, such as buttons (and to a 
lesser extent, menus). Although the principle is still the same 
(repeat the text so that it exactly matches the text that appears 
onscreen), you have to account for an aspect of human 
cognition: the mind processes graphics and text in similar but 
different ways, and forcing the reader to switch back and 
forth between these two modes of processing slows 
comprehension. You can see this easily with a simple 
example. Compare the following:

Click OK. Click OK again. Click OK one more time.
          ____           ____                    ____
Click [OK]. Click [OK] again. Click [OK] one more time.
         ------            ------                     ------

Which is easier to read? (Hopefully, the ASCII art lines up! If 
not, copy this to your word processor and realign the dashes 
and underscores so that the second line has three graphical 
buttons in it.)

So if you reproduced every button as a graphic, and every 
menu choice as a bitmap screenshot, and embedded those 
graphics directly between the words that refer to them, you'd 
end up with a page that resembled a ransom note created by 
cutting letters of random sizes out of the newspaper (i.e., the 
graphics rarely fit nicely within the lines of text). The 
resulting page would be visually distracting, and the reader's 
eyes would keep getting jerked back and forth between text 
and graphics. Writing "click the OK button" or "click OK" 
rather than inserting a graphic of the button each time is a 
reasonable compromise between visual accuracy (matching 
what you see on-screen) and reading efficiency.

One more complication: I've spoken so far primarily about 
buttons that contain text, but what about buttons that are 
purely iconic (no text)? One effective solution is to name the 
icon (e.g., "the Send Mail icon"), make sure that this name 
appears when someone holds the cursor over the button, 
include a quick reference that provides the name and function 
of the icons, and put the icon itself in the margin of the 
printed or online documentation so readers have a reminder 
of what button you're talking about. By separating the 
graphics and the text, you let readers concentrate on one 
medium at a time and obtain the maximum advantage from 
that medium; by still providing both media, you take 
advantage of the strengths of each medium. Win-win!

--Geoff Hart @8^{)}  geoff-h -at- mtl -dot- feric -dot- ca  (Pointe-Claire, Quebec)
"Perhaps there is something deep and profound behind all those sevens, something just calling out for us to discover it. But I 
suspect 
that it is only a pernicious, Pythagorean coincidence." George Miller, "The Magical Number Seven" (1956)