The Importance of Contextual Navigation, or Cross References in Topics

Contextual Navigation

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.]


In WordPress, the loop is the main code that shows your latest posts. For more information, see [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?

Madcap FlareAdobe Robohelp

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm interested in topics related to technical writing, such as visual communication, API documentation, information architecture, web publishing, JavaScript, front-end design, content strategy, Jekyll, and more. Feel free to contact me with any questions.

8 thoughts on “The Importance of Contextual Navigation, or Cross References in Topics

  1. Christina Eftekhar

    As an avid blog reader, I personally can’t stand to see a bunch of phrases turned into links on a blog. Sometimes there are so many links it hurts my eyes. Most of the time I open all those contextual links in new tabs in my browser to see if I want to read it or not. This is time consuming and annoying.

    Contextual links only slightly irritate me in online help, but I can get over it much quicker because I understand the need for it.

    The blog author may think that converting a bunch of phrases into links to other posts actually help readers. I don’t think it does; it just drives up page view counts helps the author make more money on advertisements. This is done all the time with “articles” turned into slide shows.

    If the blog author really wanted to help his readers, he should list related and relevant posts at the bottom with the ACTUAL title of the post so we readers can make a decision of whether or not we want to read them. (I think this should be a manual list and not one automatically populated based on tags or categories. A lot of times this list will change when the page refreshes.)

    This also helps readers who want to skim because they are not distracted by links they may want to click on later.

    1. Tom Johnson

      Christina, thanks for your feedback. Certainly many users over-link their content and the result can look ridiculous. On the other hand, some formats, such as wikis, rely on linking as their main means of navigation, so contextual links are paramount. The side and top nav links don’t get a reader very far.

    2. Neal

      I disagree: I appreciate links in posts because the author is doing the work for me, anticipating what I might want to know more about. For example, Dan Rutter (of Dan’s Data) does this in his blog (see as a good example). In that case, if I want to know more about soapstone, I just open a new tab, skim the Wikipedia article, then go back to Dan’s blog. I don’t have to remember to search for more info.

      I write online documentation, and PDF output is a nice feature, but a secondary concern. I just try to make sure that the PDF looks decent. Plus, links work from within PDFs. That said, I tend to use “See for more information,” because I started as a tech writer working on manuals for print/PDF. But I do that when I want to explicitly direct the reader to another topic. (“No, really, you should go read this other topic to understand this stuff.”)

      I also create inline links from terms (when I’m saying, “Oh, by the way, there’s more info over here”), which has the benefit of seeming less formal and also helps with SEO.

  2. Lopa

    I agree that inline links are useful to the reader, especially helpful in user manuals, and online help.
    I generally keep lengthy concept topics separate from the task topics. So, I always include a ‘See Also’ or a ‘To know more about…, refer topic’ link at the beginning of the task topic to let the user know that he can collect conceptual information pertaining to the task elsewhere. I try to put such reference links in eye-catchy styles; for example I prefix a screen bean character reading a book to the text of the refernce link or use some style that helps the user spot the link.
    Even in concept topics, I include links to guide the user to read more information. While including links within paragraphs of a concept topic, I always add the phrase, ‘To know more about’ before the link. This gives a feeling to the user that the link will guide him to a topic that provides him additional information, that he may or may not choose to see.

    I also include links saying ‘What Next’ to direct the user to correct topics, especially in lengthy sequential processes that run into multiple topics.

    I don’t think any user reads a manual serially from start to end. Majority of them head straight to the topic of concern, and start looking for information. In such situations, cross references and inline links are very useful to the reader as they help the user to navigate to the related topics easily.

    1. Aliya

      Lopa, you’re the one after my own heart.
      I too keep the concept/reason topics separate from instruction topics on any given feature. Therefore, each of the topic must reference to other relevant topics in the same book, ensuring that a user trying to grab the feature purpose must also have a direct way to the ‘hot-to’ of it and vice versa of course.

  3. Aliya

    I agree with what your post tries to justify. And I personally use the approach too.

    But, there are times when key points are referenced to the topics in other books (such as in our product, which is a huge one and has strongly-coupled components/features). In this case whenever a topic is removed, you can never trace (without maintaining a proper referencing sheet and and eagle-like eye sight) the affected cross-links. You may miss to remove links to the deleted topic in a few places. Here you find yourself in a real fix; either the issue is going to be caught by testers on a very critical project-release stage (as at least in our company the help manuals are tested last -better say at the eleventh hour- in the SDLC) or it’s the user who is going to face those PAGE-DOES-NOT-EXIST’s. duh.

  4. Mark Baker

    I am coming to the conclusion that we have to start thinking of hypertext as a distinct media. Some people may not be as fond of hypertext as they are of other media, just as some are more fond of videos than of books. But if we decide to write on and for the Web, we should recognize that the Web is a hypertext medium — not incidentally or trivially, but in its bones — and the hypertext is built of links.

    Reading a linear PDF in a web browser makes about as much sense as sitting in a movie theater reading a book projected on the screen. A good hypertext is rich in high quality links: that is the nature of the medium. We can, of course, debate if hypertext is a good medium for certain kinds of information, or if hypertext is a preferred medium for certain readers, but there should be no debate about whether links belong in hypertext. Hypertext without links is like movies without movement: links are what define the medium.

  5. Pingback: References and Links - Rafiki Press

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>