How to structure your documentation

A documentation project’s ultimate goal is to be read and understood by a reader. Readers need to be able to discover the information that they need. Without an defined structure, readers either won’t find information that they need or get frustrated on the way.

One of the largest benefits of a good structure is that it removes questions that keep authors from writing documentation. Starting with a blank page is often the hardest part of documentation, so anything we can do to remove this problem is a win.

Choosing a structure

Good news! You don’t have to invent all of the structure yourself, since a lot of experience-based work has been done to come up with a universal documentation structure.

In order to avoid starting with a blank page, we recommend a simple process:

• Choose a structure for your documentation. We recommend Diátaxis for this.

• Find a example project or template to start from.

• Start writing by filling in the structure.

This process helps you get started quickly, and helps keep things consistent for the reader of your documentation.

Diátaxis Methodology

The documentation you’re reading is written using the Diátaxis framework. It has four major parts as summarized by this image:

We recommend that you read more about it in the official Diátaxis documentation.

Explaining the structure to your users

One of the benefits of Diátaxis is that it’s a well-known structure, and users might already be familiar with it. As long as you stick to the structure, your users should be able to use existing experience to navigate.

Using the names that are defined (eg. Tutorials, Explanation) in a user-facing way also helps here.