Andrew's Digital Garden

The four types of documentation

There are four different types of documentation, each with their own goals and advantages. Differentiating these types before writing helps the author how, what, and where to write. This should result in better and clearer documentation.

Tutorials

Learning-oriented

Lessons that guide the reader through a series of steps to accomplish a goal. The goal and steps do not need to be realistic, they need to teach. They are oriented towards beginners. Once finished, the user should be able to understand other documentation.

Tutorials need to be useful for the beginner, easy to follow, meaningful and extremely robust, and kept up-to-date.

How-to Guides

Problem-oriented

Guides that take the reader through a series of steps to solve a real-world problem. Think of a recipe, given a goal (a dish), how do I make it?

These differ from a tutorial as they answer a question for an experienced user, not set a base for a beginner. Thus, assuming user knowledge and understanding is okay.

Explanation

Understanding-oriented

These clarify and illuminate a particular topic. Used to broaden coverage about the topic, they can take a wider view or a different perspective of what they are covering.

Explanations often aren't explicitly created, but snippets exist in other sections or throughout private conversations. They can be tricky to write, due to their boundaries being dictated by whatever the writer thinks is a reasonable area to cover at one time.

Sometimes explanations exist in sections such as 'background', 'reasoning', etc.

Reference

Information-oriented

Technical descriptions of the machinery and how to operate it. They aim to describe. They are code-determined as that's what they decribe: classes, APIs, functions, attributes, etc.

Reference docs are often blander and to the point than other documentation. Often used by those looking for information how to use a specific thing, they should aim to be clear and concise.

https://documentation.divio.com/

[[documentation]] [[writing]]

The four types of documentation