Cross-references and links

Print topic Print topic Previous topic  Next topic

In a printed manual, cross-references contain page numbers. If readers follow a cross-reference, they must leaf through the document. If readers want to be able to return to a page, they must leave a finger on that page, or they must use a piece of paper as a bookmark.

In online help, readers just have to click links. With the help of the back button, it’s easy to return to any previous topic.

So, following a link in online help is much easier and faster than following a cross-reference in a printed manual.

Advantages of cross-references and links are:

they provide context

they make it easy to find related information

they make it possible to keep topics short; optional or related information can be given in another, linked topic

Disadvantages of cross-references and links are:

Cross-references attract attention and interrupt the flow of reading.

Each cross-reference requires a decision from the reader: Read on or follow the link?

If readers don’t follow a link, they feel that they might have missed some important information—and often they have.

If readers do follow a link, they often do so without having read the complete topic. If they don’t return, they miss some information, too.

Expand /Collapse All Subsections

Text links

Cross-references or links within the text interrupt the flow of information.

Add cross-references and links sparingly. Add them only when the linked information is important in the current context.

As a rule of thumb, only add a cross-reference or link if you’d also interrupt a spoken sentence at the same position.

Don’t add a link before the important information but after the important information. When possible, add a link at the end of a topic rather than at the beginning of a topic, and add it at the end of a sentence rather than at the beginning of a sentence.

Text link within online help:

Text link within a printed manual:

Related-topic links

Other than text links, links to related topics typically appear as a list of links at the end of a help topic. Related-topic links aren’t essential; instead, they’re an extra service and suggest other topics that may also be interesting.

Traditionally, related-topic links are used in online help, but you can also have them in printed documents.

If it’s vital to follow a link, don’t add this link as a related-topic link but as a text link.

Use related-topic links only for links that readers don’t necessarily have to follow.

Add as few links as possible. Only add a link if it actually provides some value for your readers. Don’t add a link only because you feel that there’s “some” link missing, or because other topics have more links. If a topic doesn’t have any related-topic links, this is perfect because then you’ve managed to assemble all the information in one place.

Don’t add related-topic links at the beginning of a topic because this tempts users to click a link before even reading the topic.

Use a subheading to introduce the list of related-topic links and to clearly separate the list from the text.

Use “See also” if you clearly want to recommend following the links.

Use “Related topics” or “Other topics that might interest you” if following the links is optional.

 

Layering related-topic links

If you layer information and create topics of different information types, it’s a good idea to layer related-topics links as well. This is especially helpful in large help systems that have many links.

Instead of providing one long list of related topics, you can provide several shorter lists. For example, if you have the topic types “concepts,” “procedures,” and “reference information,” you can provide three lists of related topics: one list with links to related concepts, one list with links to related procedures, and one list with links to related reference topics (see also Layer information).

 

Should links open new windows?

Open all help topics in the main window. Avoid all sorts of “pop-up” and secondary windows:

Each new window interrupts the flow of reading.

Handling additional windows requires additional interaction (moving the mouse, clicking, and scrolling).

The Back button in the users’ browser or help viewer doesn’t work for secondary windows.

Users can’t print the content of the second window together with the main topic.

Tip:
If you want to hide and show some extra information that’s not always required, use expandable sections (see Layer information).

QR codes

If your product is hardware and a significant proportion of your product’s users are using mobile devices with web access, you can use QR codes to direct them from the printed manual to an electronic document on a web site. This is especially useful when you’ve created only a brief Getting Started Guide as a printed manual on paper and have the bulk of your information online.


Designing: Link character styles

Writing: Writing cross-references and links