Advent of Technical Writing: Navigation Links

This is the second post in the Advent of Technical Writing series, wherein I will share something I have learned from my experience as a technical writer. My experience is primarily in software technical writing, but what you read may apply to different fields, too. View all posts in the series.

As you write and organize technical documentation, there is an important muscle to build up: creating effective navigation link text. Navigation links are what you may include in a sidebar or a top navigation bar. These may be different than the actual title of a page, since you often have more space in a page title.

You may be wondering: "what constitutes an 'effective' navigation link"? An effective navigation heading is one that:

1. Is short, ideally no more than four or five words. How many words you can use will depend on if the link is in a sidebar, a dropdown, or a top-level navigation link. In general, use as few words as you can.
2. Summarises exactly what a user will learn to do. For example, "Managing indexes" or "Create a Project" or "Search a Dataset".

Consider the following three examples:

• "How to export data"
• "Export data"

While both are descriptive, the second link is more direct. "How to", when used across many links, will be repetitive. Navigation links in documentation already imply that a user is going to learn how to do something, or acquire the knowledge they need to make a decision or solve a problem. Thus, words like "How to" are often superfluous.

If a user could export different types of data, and the flows are different, we could have a subheading in navigation called "Export", with links for each type of export. A link may only take the anchor text of the name of the data to export, since the heading would give information. Here is an example:

• Heading: Export Data
• Links:
• Images
• Annotation Statistics

Here, we don't need to say "Export Data" every time, since it is implied by the heading.

Links should be under a relevant heading. Here is an example from some documentation I wrote on deploying a computer vision model, under the heading "Datasets", a product feature:

• Create a Project
• Upload Data (expands to specific ways you can do this)
• Search a Dataset
• Create a Dataset Version
• ...

Every heading is direct and action-oriented. To the extent that you can reduce ambiguity in documentation, do. Effective navigation links go a long way in helping the user find exactly for what they are looking.

This advice pairs with the first guide in the series, in which I talk about how to structure navigation links.