The Importance of Contextual Navigation, or Cross References in Topics

by Tom Johnson on Jul 23, 2012
categories: findability

One of the most hotly debated topics in tech comm deals with how writers should cross reference other topics within a help topic. Some writers feel that including contextual or inline links in your help topics distracts low-literacy readers by encouraging them to navigate elsewhere. The low-literacy readers, they argue, end up bouncing from page to page, following one internal link to the next, without ever completing any page's full message. (For more information on how internal links hurt readability, see Embedding Links and Online Accessibility, an interview I did at a previous STC Summit.)

Another group of writers believes that omitting internal links due to readability is non-sense, that readers skip from one page to another because they are looking for the right information and aren't finding it. They leave a page not because they're distracted by an exit link, but because they're still looking for the right information. As such, embedding more links within your content provides a wayfinding technique to help users locate information. (See Re-thinking Inline Links: DITA Devotees Take Note, an excellent article by Mark Baker.)

Contextual Links Provide ... Context

Overall, contextual links provide one of the strongest navigation methods for users due to the context they provide. In a table of contents, the user usually has little context about the meaning of the link. But when you include the cross reference directly in a paragraph on a page, readers have all the page content as context for the link. As a result, readers have a much better idea about the link. The abundant context for inline or contextual links makes these links such a good technique for wayfinding.

Additionally, readers often do not use your site's navigation to land on your content. Think about the last time you searched for something on Google. You probably started reading the page where the term appeared, gathering more context about relevance of the result. If links for more information appear directly in the page content you're reading, you'll likely to follow those links rather than look to navigate the site's content through a top menu bar or sidebar navigation. Again, the context surrounding the link guides the reader in powerful ways.

Publishing Complexities of Contextual Links

Perhaps technical writers feel so strongly about contextual links because of the publishing complexity these links introduce with single sourcing. If you single source your content into multiple deliverables, you have to ensure the cross-reference in one topic doesn't point to a topic that isn't included in your output.

For example, let's say you have a Beginner's Guide, a Publisher's Guide, and an Administrator's Guide. In the all three guides, you have a topic called "Managing Categories." In the topic, you reference a related topic called "Converting Categories to Tags." The topic "Converting Categories to Tags" is a task only administrators can do, so only the Administrator's Guide includes this topic. Therefore your cross-reference needs to be conditionally included in just the Administrator's Guide while being excluded from the other two guides.

Multiply this same kind of scenario for every cross-reference, and your conditional text can become a headache. About the only solution is to create a grid of all your topics and your deliverables (putting topics in the left column, deliverables on the top row), and then add a X in row for deliverables that contain the topic.

Relationship Tables

One way around the complicated grid technique is to use relationship tables. A relationship table includes a set of links at the end of your topic. The links will point to other topics only if those topics exist in the output. If the topic doesn't exist, the link is not shown. Relationship tables are a smart way around the problem of deciding what topics are included in what outputs. (See my post on Discovering Relationships Tables for more information.)

Relationship tables seem like a neat solution, but they don't include the cross reference in the appropriate place in your content. Many times you may want to briefly allude to a concept or idea and then refer readers to another topic for more information. If you omit this referring sentence in the context when it would be most helpful to readers, you lose a lot of the immediacy and relevance of the cross reference. Ultimately a relationship table is no better than a "See also" list of links at the end of a topic.

In Designing Web Navigation, James Kalbach says that contextual links help readers discover information they wouldn't otherwise know to look for. Kalbach writes,

Contextual navigation doesn't support known-item seeking well. Instead, it supports exploration and may point people to new information. For a business standpoint, contextual navigation provides opportunities for upsell. Product pages in e-commerce sites, for instance, often have links to related products and services. (p.93)

In other words, the contextual navigation gives readers opportunities to learn about new information they wouldn't have otherwise thought to seek out. In that case, merely listing a link at the bottom of a topic loses the power of the upsell. The reader may not understand how the new link connects with the current concept or technique, because the reader isn't particularly looking for that information in the first place. Without more forcefully bringing in to the reader's attention, the link gets lost in the background.

Inline Link Styles

If you're going to include internal links, you have some choices about how to style those links. If you're accustomed to using a web style, you might think that hyperlinking a word or phrase is a good way to include a link. For example, when you read the following online, there's nothing confusing about the sentence:

In WordPress, the loop is the main code that shows your latest posts.

However, consider what this same text looks like when you single source it to print:

In WordPress, the loop is the main code that shows your latest posts.

You can style the print output so that hyperlinks look like regular text (as I assume one would do with a print deliverable). The problem is that the reader now has no idea where to get more information about the loop. Perhaps you could leave the link styled as a link, with blue font and underlining. However, assuming the user will print the guide, often in black and white, the user cannot tap or click the paper to go to the link. The user is not told about where to get more information.

If you plan to push content to print, it's better to include the cross reference spelled out, like this:

In WordPress, the loop is the main code that shows your latest posts. For more information, see "The Loop" on page 23. [This assumes "The Loop" is a topic in your help.]

OR

In WordPress, the loop is the main code that shows your latest posts. For more information, see http://codex.wordpress.org/The_Loop. [This assumes the link falls outside your help system.]

Now the reader can know where to go for more information.

If you plan to leave the print version bereft of cross references altogether, hoping that the sentence would make sense without the link at all, you put a lot of cognitive strain on your style.

In WordPress, the loop is the main code that shows your latest posts.

Now every time you include a link, you'll need to make sure your sentence reads well even if the link doesn't appear in print. That might be okay for the above sentence, but what about this one:

In WordPress, one key feature you must understand is the loop. The loop is integral to the way all content is displayed. Beyond the loop, publishing also requires knowledge of other PHP tags.....

The reader may be thinking, uh, if the loop is so important, can you give me any tips on where I can read more about it?

If some links render well in print when removed, and other links introduce confusion without more information, writing becomes more of a dance of decisions that will slow you down. It's better to adopt a style that will work almost every time.

As long as the outputs aren't too confusing, I prefer to include links directly in the paragraph where they make the most sense to appear, rather than later at the end. I typically don't have so many outputs that the inclusions and exclusions become overwhelming.

Overall Strategy

When you include inline links, your strategy should depend on your medium. If you're writing blog posts, link freely and abundantly, without worrying about how your printed versions will look because blogs are primarily online and not printed. For example, when I read Penelope Trunk's posts, she includes a ton of inline or contextual links. These links actually have a tremendous SEO boost even when they just point to your own site. Case in point, have  you ever wondered why Wikipedia ranks so well in search results? In part, it's because they have a jillion internal links pointing from one Wikipedia entry to another.

But technical writers, unlike web writers, often have single sourcing matters to consider. As such, they have to follow a different strategy. My recommendation is to link where appropriate in the right paragraph, rather than at the end of a topic. If you have seventeen outputs with a complicated array of topics that are included and excluded, you may want to consider reducing these links or even using relationship tables. But if you only have several outputs, it shouldn't be so complicated that you have to hire a neuroscientist to keep the conditional formatting straight.

I also prefer putting links for more information into their own sentences (such as, "For more information, see ...") rather than converting phrases into links. The former style accommodates a printed output that readers can understand.

I'm curious to hear about your strategy for contextual links. Do you welcome them in your help as a wayfinding technique, or do you omit them due to publishing complexity and readability considerations?