Build documentation that developers can actually navigate

Estimated reading time: 5 minutes

Documentation can be a pain for developers to write and navigate alike. But following this framework might be just the thing you need to make document navigation easier. 

Documentation is the lifeblood of any high-functioning team. At a high level, documents are written to outline the feature processes, details, and general “how-to” elements of a system. The result? A bank of saved knowledge that helps new developers get up to speed quickly, providing a common reference point for all necessary stakeholders.  

A common pain point for many teams is unstructured documentation. Without clear guidelines, it’s hard to organize information in a way that’s easy to digest or search through. My team faced this problem when creating onboarding documentation for our new AI product; this would ultimately be used by engineers at client companies integrating the product into their systems.

We adopted the Diátaxis method as our guiding framework for technical documentation. The Diataxis approach identifies four distinct user needs in documentation: tutorials, how-to guides, explanations, and references.

Ultimately, this led to our documentation process improving and our user experience boosting. 

Your documentation structure should be intuitive 

While the advantages of documentation are manifold, developers (including myself) tend to skip dipping into them if they appear to be unstructured or have an undefined goal.

Each page should have a clear purpose. This sets expectations and helps engineers identify which pages answer their questions. Organizing pages with anticipated questions at the forefront of the design can help you build documentation that engineers navigate more intuitively.  

Put yourself in a developer’s shoes. If they’re using a product for the first time, what questions would they likely ask? 

• If I want to do X, where can I go and learn about it? 
• Where can I learn more about concept Y? 
• Where can I find a code example so I can try Z myself? 

Structure your content with user needs first. When your docs are built around real questions, they become easier to flick through and far more useful. 

Avoid packing too many ideas into one section. In doing so, you might create a long-winded document that jumps between topics and leaves explanations of singular issues scattered across multiple pages. 

The documentation solution: Diátaxis

The Diátaxis framework outlines how documentation is composed of three key elements:

• Content: What you write
• Style: How you write it
• Architecture: How you organize it

Some developers have the skill for content and style, but could bolster their architecture abilities.

What’s unique about Diátaxis is that it addresses the challenges of technical writing and breaks them down into four key sections: tutorials, how-to guides, explanations, and references.

The two quadrants, tutorials and how-to guides belong in the action region. Tutorials and how-to guides are not meant to be consumed passively by readers; rather, they actively help devs learn a new skill or achieve a specific goal.

The two bottom quadrants, explanations and references, belong in the cognition region. These are resources that readers can read or skim to understand and grasp the essence of a solution. 

Tutorials and explanations are about skill acquisition. They’re designed to teach – not to solve an immediate task, but to build understanding. The goal is to help readers pick up a new skill relevant to the new tool or product they’re working with. 

How-to guides and references are about skill application. They’re for readers who have already learned the basics and are now ready to put that knowledge into action. 

How to get started on building a useful docsite

When we started to build documentation for our product, we geared the content toward two different technical stakeholders: data scientists and AI engineers. After all, our goal was to have data scientists lean on our AI product when running simulation experiments, subsequently empowering engineers to deploy these experiments to production.

Before embarking on writing the documents, we defined two main personas and described some key qualities about them to better identify what documentation we needed to create. Let’s call them Alice and Bob.

1. Alice is a data scientist with an interest in building forecasting machine learning (ML) models. She is a detail-oriented person with a background in mathematics and likes to test out new ideas when possible. She is not familiar with modern software development and mainly works with Jupyter notebooks and AWS Sagemaker.
2. Bob is a software engineer with a passion for building AI applications. He is a self-taught developer. He learned back-end engineering and has experience in deploying production apps. He likes to test new features and play around with large language models (LLMs), but is not directly involved in AI training or fine-tuning. He is familiar with the back-end fundamentals, CI/CD, and can debug deployments.

Once we defined our two main personas, we designed the following navigation bar for our docsite:

We have six main “folders” with a defined purpose for each, highlighting the experience level required. The first three folders are meant for beginners or users being onboarded. The next three folders are for already-onboarded users, who have specific goals they want to achieve or details they want to look up. 

Note that some of these folders may not be necessary for your solution. For example, if you’re not introducing new abstractions or concepts that readers need to know about, the “concepts folder” may not be required for your docsite.  

Afterwards, we assigned our developers to write different parts of the documentation following this architecture for the two main personas, Alice and Bob. Here are some examples where we map a question to a folder.

• “Alice doesn’t know how to run a simulation.” → [How-to guide] 
• “Alice wants to look up the APIs for running a simulation.” → [API reference] 
• “Bob wants to learn how to deploy an ML model.” → [Tutorials] 
• “Bob wants to learn more about the underlying architecture” → [Concepts] 

As Alice and Bob become better acquainted with the resources, so too does their mental model of the documentation’s architecture. This helps in instances where they may need to help newer colleagues navigate the system. For instance, if Alice is working with the APIs and wants to onboard a new data scientist, she can pull from previous experience and quickly direct the data scientist to the right folder. 

Final thoughts 

Strong developer documentation can be a major selling point for a product. Developers do not trust using a new product in their tech stack unless they can understand its underlying details and have clear product documentation to search through. 

So it’s your job to create a comprehensive database of knowledge that can support devs while they get to grips with your product. 

Get articles like this in your inbox

Choose your LeadDev newsletters to subscribe to.