How to write documentation

The best way to think about documentation that I have come across is from Daniele Procida. He explains it in his talk at PyCon Australia 2017, and in a standalone website.

The basic idea is that there isn’t just a single kind of documentation—there are four:

  1. Tutorials
  2. How-to guides
  3. Reference guides
  4. Discussions

Each serves a different purpose and has its own stylistic considerations.


Tutorials

Tutorials are learning-focused.

They take the form of a lesson, and are meant to help a beginner get started with an activity. They should inspire confidence, include lots of activities, and minimize distractions.

Food analogy: teaching a child how to cook.

How-to guides

How-to guides are problem-focused.

They take the form of a series of steps, and are meant to help the reader solve a specific problem (often one that a beginner wouldn’t even know how to formulate). They should be focused and algorithmic.

Food analogy: a recipe in a cookbook.

Reference guides

Reference guides are information-focused.

They take the form of dry description, and are meant purely to “describe the machinery”. They should accurate, up-to-date, and structurally and tonally consistent.

Food analogy: an encyclopedia article about an ingredient.

Discussions

Discussions are understanding-focused.

They take the form of a discursive explanation, and are meant to help the reader understand a concept, a philosophy, or a history. They should provide context, and avoid instruction.

Food analogy: an article on culinary social history.


Documentation is useful to the extent that all four forms are both present and separate.

As soon as they start to bleed into each other, the documentation becomes a rat’s nest—hard for readers to navigate, and hard for authors to maintain. The temptation to blend them is explained in this amazing 2x2:

  • Tutorials and how-to guides are practical, while discussions and references are theoretical.
  • Tutorials and discussions are useful when studying, while how-to guides and references are useful when coding.

References

Links to this page