Style for hyperlinks?

Subject: Style for hyperlinks?
From: "Geoff Hart" <Geoff-h -at- mtl -dot- feric -dot- ca>
To: TECHWR-L -at- lists -dot- raycomm -dot- com
Date: Thu, 7 Oct 1999 09:27:27 -0400

Karen Casemier is << 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
that it is only a pernicious, Pythagorean coincidence." George Miller, "The Magical Number Seven" (1956)

Previous by Author: Squashed egos... it ain't pretty!
Next by Author: Helping your colleagues use a standard template?
Previous by Thread: Re: WAS: Squashed egos Now: 400% Longer
Next by Thread: Re: Ancient History of Writing

What this post helpful? Share it with friends and colleagues:

Sponsored Ads