Advent of Technical Writing: Navigation Structure

This post was going to begin with "Last year, I wrote 24 blog posts about bloggers whose content I followed." Until a voice in the back of my head said "wait, maybe I did that the year before." It turns out that is the case: my Advent of Bloggers series, where I wrote about blogs I liked, is two years old. I am in disbelief. Time does indeed fly.

I have been pondering about what to write today and I started to think about technical writing. As is the origin of many ideas, I combined my Advent of Bloggers series with technical writing (in general), to come up with a new series. Herein begins Advent of Technical Writing.

Over the next 24 days, I am going to share one lesson I have learned when writing technical documents. My experience pertains almost exclusively to software technical writing. I expect that much of what I write will be more applicable in that domain, but I hope my advice can generalise. This series will use a lot of "I"s, because I want to write with direct reference to my experience. You may have your own style that deviates from mine; therein lies the beauty of writing. But perhaps you will learn something from what I write!

This series is for everyone interested in technical writing, whether you are a beginner (like we all are at one point!), someone who writes a bit of documentation at work and wants to improve, an expert, or anything in between.

Without further preamble, let's start the first edition!

Navigation Structure

Over the last year, I have led the development or restructure of several documentation sites, both at work and for personal projects.

As I write documentation, I pay a lot of attention to the navigation structure. This comprises a number of elements, including:

1. Whether you use a sidebar or a top navigation bar (or both) to allow people to find for what they are looking;
2. Deciding on the order in which documents appear in navigation;
3. Deciding on subheadings to organise content, and more.

I want to focus in on the second point above: ordering documents.

I commonly use a sidebar for technical documentation, in large part because the tools I use most for documentation sites (mkdocs and GitBook) both have well-designed sidebar features. When I write, or update, documentation, I always ask myself the question: in what order do I want someone to learn about the thing I am documenting?

I want someone to learn the "what is" as soon as possible, then provide a quickstart to get someone using the software. The quickstart should be use as little nomenclature as possible. When jargon is used that I cannot comfortable assume the audience will know, I aim to define said jargon. Quickstarts are effective because they are a single point to which someone can go to use your software; a reader doesn't need to jump around to try and find an entry point. In most of my writing, the outcome of a quickstart is running a project on one's own machine, but the aim will vary depending on the project you are documenting.

After the user has had a chance to experiment with the software through the quickstart, I want to graduate the reader into exploring more key value propositions that were not explained in the quickstart. Then, I go on to more advanced information, including reference material.

Let me talk through an example.

Consider Inference, an open source inference server that lets you run computer vision models on your own hardware. I started off by thinking about everything that I wanted to include in the documentation. Then, I divided the information into a few key sections applicable for the project. Here are the general sections of content I wrote, in order of how they appear in the sidebar:

1. A home page: The first place a person lands. I wanted this to be visual and provide a great summary to encourage someone to get started.
2. A list of "Getting started" guides which covers one of the main value propositions, and the topic that I decided was the most appropriate entry point: running a fine-tuned vision model on one's device.
3. A "Run a Model" section with guides on how to run a model. Each tutorial is titled "On a...", such as "On an Image (Using HTTP)." With the sidebar heading as context, each link concisely states exactly what each guide does.
4. "Use a Foundation Model", which documents the foundation model features in Inference. These features are important, but are more effective to read once you know about how to run a model.
5. "Integrate with Inference", which includes more advanced documentation.
6. "Reference", which includes miscellaneous reference information that someone may use with the library.

This sidebar appears on the homepage, and all of the pages linked in the sections mentioned above. The sidebar changes if a user navigates to a different area of the site using the navigation bar at the top of the page. The link "Home" always appears in the top navigation bar, allowing a user to get back to the above documentation, which covers the most important parts of using Inference.

My goal for the documentation was to achieve the following in order:

1. Tell someone what the product is.
2. Tell someone how to use it as soon as I can.
3. Highlight key value propositions, in order of relevance to a beginner:
4. Running a model on images, videos, webcams, and streams.
5. Using foundation models.
6. Using the SDK integration.
7. Including important reference material that users will need.

The structure above assumes you are documenting a single product. For a site that documents multiple products, you may choose to have different subheaders in a sidebar for different products, or different links in a navigation bar at the top of the page that takes people to different product home pages or guides.

I like Supabase's structure, where they have a parent sidebar and child sidebars for each product or topic area. For example, "Database", their flagship product, is at the top of their "Product" sidebar section. This section is directly below their quickstart. If I click into "Database", the sidebar is replaced with guides related to their database product. I can always navigate back by clicking the "Back to Home" link that appears.

Generally, be conscious that document order matters. Order guides in such a way where a new reader can easily find for what they are looking.

Join me tomorrow for another tip!