A link consists of the link text and the link destination. Links enable readers to jump to related information with a single click. Links are one of the advantages of online reading because they enable readers to make their own decisions about how to access information.
However, links pose challenges for writers. Too many links clutter text and can distract readers. Too few links mean readers might have difficulty finding the supplemental information that they need when looking at a screen of text, which lacks the context of a printed page.
This chapter discusses the following topics:
“About These Guidelines” on page 101
“Where to Place Links” on page 102
“General Linking Strategies” on page 103
“Guidelines for Writing Link Text” on page 110]
The guidelines in this chapter focus on online text that is intended to be read in a web browser, such as technical documentation on a Web site. This chapter does not discuss software tools, web browsers, screen design, graphics, or document delivery methods. Underscores before and after link text show where to place links in the text.
The online writing guidelines in this chapter do not apply to the following types of documents:
PDF documents
PostScript documents
This chapter uses the word “page” to refer to an online page or web page. A “page” is equivalent to an online file or web file. When “printed” precedes the word “page,” the reference is to hard copy.
When considering which links to create, anticipate paths that your readers are likely to take. Which associations would benefit them? Let your readers’ needs, expectations, and interests guide you. Create links that support good decision making.
When readers must follow a certain sequence through your content, for example, when following a procedure, limit their choices by reducing or eliminating links. At the least, guide readers with additional explanatory text.
Except for such instances, your goal is to provide readers with opportunities, not to order them around. However, do not make these opportunities endless. You must set priorities in your documents and point your readers in relevant directions.
The following list suggests ways to use links in online documents.
Tables of contents. If your writing tool does not generate a clickable table of contents for you, include one as the entry point into your online document. If your writing tool can expand and collapse entries for tables of contents, use this feature.
Summaries. To reduce the amount of information that readers see, briefly summarize content and then link to supporting details. For example, you can link to long examples and to overview, background, reference, detailed, or supplementary information.
If you organize your document by hierarchy, you can present general overviews that link to increasing levels of details. See “Organize Text by Hierarchy” on page 84.
Lists. Online readers interpret links more easily in bulleted lists rather than links embedded in paragraphs. A jump list can serve as a short table of contents or a brief summary of the content if it is placed at the beginning of a chapter or main section of a document.
For more information, see “Use Jump Lists” on page 97 and “Provide Links in a List” on page 108.
Tables. Tables with links to related information provide scannable content and quick access to more details. See “Organize Text by Table” on page 87 and “Tables” on page 42.
Cross-references. Cross-references to other sections, chapters, or manuals typically become links embedded in the text. Consider clustering cross-references to headings or titles under a “See Also,” “Related Topics,” or similar heading.
Capitalize and punctuate cross-references by following the rules in “Formatting Cross-References” on page 48.
Code examples. Consider placing long blocks of programming code in a separate text file. Then, link to the text file from your document. This strategy eliminates the formatting cleanup that is often necessary when a user cuts and pastes code from documents displayed in a web browser.
Glossary terms. Wherever the prominent use of a glossary term appears, link to the document’s glossary if the document has one. In determining the prominent use of the term, consider the reader’s likely path through the document. Remember that too many links can distract readers. Balance the desire to provide helpful links to the glossary against the risk of overlinking.
Reader comments. Include an online feedback mechanism on every page of your online document if you have control over this information design feature. Direct comments to the appropriate group, not, for instance, to the webmaster if your document is displayed on the Web. Also, let users know if they should expect a response to their comments.
Reference lists. A document such as a white paper can link to a reference list that is contained in a separate page. In print, the reference list would be contained within the body of the paper.
Other relevant web sites. For web documents, links to material on other sites enable you to take advantage of what others have produced. For information about policies for linking to third-party Web sites, see “Third-Party Web Site References” on page 162.
Links stand out by virtue of being underlined and displayed in color, so think of them as emphasized words. Because the scanning eye notices only two or three words at a time, emphasized or not, make the link text short but informative. In addition, be sure that the links on a page collectively offer context about what that page contains, not just where each link leads.
When constructing links, use these general strategies:
Create links that anticipate readers’ likely paths.
See “Where to Place Links” on page 102.
Avoid overlinking.
Prevent reader disorientation.
Include links that answer readers’ questions.
Use links to condense the amount of information readers see.
Provide links in a list when possible.
Place links at the end of a topic when possible.
Provide URLs only when needed.
Test the validity of links.
Be careful about filling text with distracting links. Too many links dilute the message on a page and can confuse readers with irrelevant digressions. You need to guide readers and filter their choices.
Links also disrupt the narrative flow of text by inviting readers to go elsewhere. Unless that is your goal, link sparingly. Also, remember that too many links can involve too much maintenance and that they are hard to read on a cluttered screen.
The following sections suggest ways to avoid overlinking.
If you do not want to interrupt the reader at a certain point in the text, do not put a link there. Ask yourself: Is the information at the link destination relevant to the audience, purpose, and content of this document?
Do not repeat a link wherever the link text occurs.
Identifying a link once per topic is sufficient.
Incorrect:
PlirgSoft uses __file folders__ to organize your files. These __file folders__ can contain only graphic and text files.
Correct:
PlirgSoft uses __file folders__ to organize your files. These file folders can contain only graphic and text files.
Do not link to an online feedback mechanism more than once on a page.
Avoid making explicit cross-references if they create redundancy.
Incorrect:
If you used __Wrap To Fit__, the Save dialog box includes an additional choice about handling line endings (see __Wrap To Fit__).
Correct:
If you used __Wrap To Fit__, the Save dialog box includes an additional choice about handling line endings.
Do not add a link if you can succinctly present the information in the current topic.
In the following incorrect example, readers need to click twice to access the Application Builder User’s Guide. The first click, __click here__, takes readers to the list of related documentation. The second click, which is not shown in the example, takes readers to the user’s guide. In the correct example, readers need to click only once to access the user’s guide.
Incorrect:
For related documentation on Application Builder, __click here__.
Correct:
For related documentation on Application Builder, see the Application Builder help volume and the __ Application Builder User’s Guide__.
Especially if a page is short, do not link to other destinations on that page.
Readers typically expect links to take them to another page. If a link takes readers only a few lines down, readers can become disoriented.
When a table, figure, or example immediately follows a textual reference to it, do not include a link.
The unnecessary link can disorient and frustrate readers, especially if clicking on the link renders an entirely new web browser that contains only that structure.
In the textual reference to the table, figure, or example, use the word “following” to indicate the structure’s location. For example, you might begin the sentence with the text “The following figure shows.”
Ensure that readers remain fully oriented and in control as they navigate through an online document. Readers are properly oriented when they can identify the content presented, the location of the content within the larger body of information, and the navigational options.
The following techniques can help prevent disorientation:
Reserve link formatting for links only.
Never use your link formatting convention for any other purpose. Links are usually identified by underlining and a certain color.
Label navigational icons.
Label navigational icons if you have such control over them. Some users are visually oriented while others are text oriented. A combination serves all users.
Provide sufficient context.
Sufficient context helps readers decide whether to follow the link. Explain what information is located at the link destination and how it relates to the present topic. See “Provide Context in Link Text and Surrounding Text” on page 110.
Warn readers about unexpected link destinations.
Let readers know when a link might take them to an unexpected destination. For example, tell readers when clicking on a link does the following actions:
Opens another document
Opens another application
Takes them to another site
Leads to a large file with a long download time
Requires them to register or enter a password to access the destination
If you carefully word a link and its surrounding text, readers know when the link takes them away from your document.
In the following example, links to “VI” and “Emacs” take readers away from the tutorial. The correct version clearly indicates that clicking on either link takes readers to another site.
Example 5-1. Preventing Reader Disorientation
Incorrect:
Pico is probably the easiest of the three editors to use. If you are curious about how to use the other editors, however, see the reference cards for __VI__ and __Emacs__.
Correct:
Pico is probably the easiest of the three editors to use. If you are curious about how to use the other editors, however, see their reference cards:
__VI Reference Card__ from Dalhousie University
__GNU Emacs Reference Card__ from
www.geek-girl.com
One reason for providing links is to answer the reader’s questions, such as “How do I compress a file?” Ideally, write link text so that it corresponds to the reader’s search tasks.
Incorrect:
Bug voting provides another channel for feedback and for establishing priorities. You can cast a vote on the bugs that frustrate you the most. Your votes are viewed by engineering. If you want to vote, __click here__.
Correct:
Bug voting provides another channel for feedback and for establishing priorities. You can __cast a vote__ on the bugs that frustrate you the most. Your votes are viewed by engineering.
Your online document might be lengthy. However, with links, your text can appear shorter to readers without sacrificing depth of content.
Link to in-depth information.
Use summaries and link to supporting details. See “Summaries” in “Where to Place Links” on page 102.
Link to, rather than duplicate, information.
For example, if a procedure is basic and frequently used as part of other more complex procedures, do not repeat the steps of that basic procedure. Instead, put the steps for the basic procedure in one section and link to it from other places.
Also, do not duplicate background or overview information. Include this material in one place and link to it from other places, as needed.
Link to basic information.
Link to basics so expert users do not stop reading. Novice users can access the material if they are interested.
Try to use a list of links instead of links embedded in the text.
Searching a list of links rather than a paragraph with embedded links reduces the mental processing demands of online reading and link interpretation.
Incorrect:
The installation of the application server is affected by the following resource issues: __unique network ports__, __shared directory configuration trees__, __shared environment__, and __login__.
Correct:
The installation of the application server is affected by the following resource issues:
__Unique network ports__
__Shared directory configuration trees__
__Shared environment__
__Login__
Carefully craft the link text, and annotate each link, when necessary, to ensure that readers can easily decide which links to follow.
To encourage readers to stay with a topic, place links at the end of a topic, when possible. Readers might read all or at least some of the content before moving on.
In the following incorrect example, the link text falls in the middle of the paragraph. In the correct example, the link text falls at the end of the topic.
Incorrect:
You can install the application server by using
setup.exeorezSetup.exe. The ezSetup method provides an easy installation without requiring various inputs. For more information, see __Using ezSetup__. However, this section covers thesetup.exeinstallation options: Express, Typical, and Custom installations. The Typical option is the default.Correct:
You can install the application server by using
setup.exeorezSetup.exe. This section covers thesetup.exeinstallation options: Express, Typical, and Custom installations. The Typical option is the default.For an installation that does not require various inputs, use the __ezSetup method__.
Use URLs in the following instances:
When readers are likely to print the page and then later retype a URL on that page in a web browser
When your online document is also available in print
When your goal is to raise awareness of a site
Reserve this usage for short URLs only, because readers are unlikely to remember long URLs.
Make references to URLs as simple and as direct as possible. For suggestions on how to introduce URLs in text, see “Referencing URLs” on page 228.
When writing link text, apply these guidelines:
Provide context in link text and surrounding text.
Weave link text into sentence structure.
Choose key words or phrases for link text.
Choose an appropriate length for link text.
Write scannable link text.
Make link text conceptually similar to titles or headings of link destinations.
Do not use quotation marks around link text.
Readers use links as guideposts when scanning, so take full advantage of them and word your link text accordingly. Effective link text also creates adequate context for readers and reduces the likelihood of readers becoming disoriented.
Choose your link text carefully, as well as the text that surrounds the link text.
If possible, supply explanatory text before the descriptive link.
This additional information helps readers understand where each link leads and why it was chosen.
Incorrect:
__Appendix F__ identifies the system components.
Correct:
For a list of the Plirg 5763 system components, see __Appendix F, Illustrated Parts Breakdown__.
Incorrect:
The combination of hypertext and the global Internet started a revolution. In __this article__, published in Scientific American, Jon Bosak and Tim Bray tell how a new tool, XML, is poised to finish the job.
Correct:
The combination of hypertext and the global Internet started a revolution. Jon Bosak and Tim Bray tell how a new tool, XML, is poised to finish the job. See the Scientific American article, __XML and the Second-Generation Web__.
Make the text of the link meaningful and part of the natural syntax of the sentence.
Do not make the link text refer to the mechanism of the online display tool, as in “click here” or “go here.”
One exception is when readers need to see the URL of a web document. See “Provide URLs Only When Needed” on page 109.
Incorrect: __Click here__ for more information about Plirg File Manager.
Correct: For more information, see __Plirg File Manager__.
Note that using a list of links is almost always preferable to embedding links in the text. Placing links at the end of a topic is also preferable.
Choose key words or phrases in text that best represent the content of the destination.
Incorrect:
__How do you__ set Netscape™ Messenger to use the POP protocol?
__What are__ known problems with the Netscape Communicator for Plirg products?
__Netscape Communicator 4.x Frequently Asked Questions__
In the correct example, the wording of the third question in this example has changed. The reworded text removes the long, unbroken line of link text and presents two different link destinations. Readers now have two link choices instead of one.
Correct:
How do you __set Netscape™ Messenger to use the POP protocol__?
What are known __problems with the Netscape Communicator__ for Plirg products?
__Netscape Communicator 4.x Frequently Asked Questions__ from Netscape’s site
_help.netscape.com_
A link that is the length of a complete sentence is too long and difficult to read. One to three words usually works best, as long as those words are context-rich. Using more words is acceptable if they provide helpful context.
Incorrect:
Plirg 5763 System:
__Plirg 5763 Installation Guide (Download)__
__Plirg 5763 Maintenance Manual (Download)__
__Plirg 5763 Parts List (Download)__
Correct:
For the Plirg 5763 system, you can download the following information:
__Installation Guide__
__Maintenance Manual__
__Parts List__
Write links as though your reader were scanning only the links on the page. As the eye processes a page, it jumps to the links, so make them self-explanatory and scannable.
Incorrect:
There will be a moderated online chat on the PlirgSoft API for XML Parsing (PAXP) on Tuesday, April 25, at 11:00 a.m. Pacific Daylight Time. The guests are Wallace Gromit, Plirg architect–XML technologies, and XML parser guru Laurel Hardy. To join the chat, go __here__.
Correct:
Join the __online chat__ on PlirgSoft API for XML Parsing (PAXP) on Tuesday, April 25, at 11:00 a.m. Pacific Daylight Time.
The guests are as follows:
Wallace Gromit, Plirg architect in XML technologies
Laurel Hardy, XML parser guru
Check that the text of all or most of the links in a topic are conceptually similar to the title or headings of their associated link destination.
Also, use consistent wording for link text that leads to the same link destination, if possible. For example, if you have a __Feedback Form__ link at the top of your multipage document, do not use the link text __feedback page__ elsewhere in the same document.