TIL: The Documentation System (Divio)

The Perfetto team spent a lot of time earlier this year rewriting our documentation to be more useful for the average developer. We struggled a lot to figure out “what is the best way to structure our documentation”.

When reading Examples are the best documentation today, I came across The Documentation System, an approach to structuring developer documentation. Reading through it, I couldn’t help but marvel at how clear and concisely it laid out the ideas we were struggling to come up with from first principles.

Specifically, I really like how it breaks down documentation into four quadrants:

1. Tutorials: take your user through a series of steps to complete some task with your project.
2. How-to guides: solve a real world problem with your project.
3. Reference guides: give technical explanations of how things work.
4. Explanations: clarify a particular topic or area and how the project fits into the bigger tech landscape.

I think we got most of this right in our documentation rewrite but we definitely muddled some of these areas together, making our pages less clear than they could be. I plan on spending some time later this year correcting our docs to match this system closer.