Skip to content
Ritza Documentation

Structuring your documentation

There’s no best way to structure your documentation, and you’ll definitely need to restructure it several times as it grows.

At the beginning, just write content. Keep the structure flat, and don’t worry if things don’t fully make sense. Most people are going to be using search tools to find relevant content instead of navigation anyway.

The Divio Documentation Structure is a very popular way to think about different kinds of documentation.

We don’t usually recommend that you literally have four categories on your documentation site, one for each type of documentation, but this can be a good way to start off.

Repeat yourself

Software developers often tend to build documentation that is too complicated by trying to factor out common pieces that need to appear in several places. The most common way people fall off a guide is when it link to some other document, so we prefer to have some repetition where it helps keep each page independent.

There will always be some tradeoff between making things as easy as possible for the reader (having all the information they need on the same page), and making sure that your documentation site is maintainable (by not having to update the same information in 100 different places).

In general, we see people err far too much towards having documentation that is easier to maintain at the expense of the user experience.

There are two kinds of repetition you might be tempted to skip, where it’s often better not to

  • Skipping over stuff that already appears in another guide or piece of internal documentation on your site
  • Skipping over stuff that already appears in some third-party documentation

Documenting other people’s systems that your users want to integrate with often feels like it’s “not your job”. But linking out to third-party documentation is risky as it might change, and usually it’s not exactly right for what you need anyway.

So in both cases, we usually recommend biting the bullet and putting in the extra work to maintain duplicate information in your own docs and to document third-party systems in your own documentation wherever it might be helpful to your readers.