Documentation System

It doesn’t matter how good your product is, because if its documentation is not good enough, people will not use it. Even if they have to use it because they have no choice, without good documentation, they won’t use it effectively or the way you’d like them to. page

Nearly everyone understands this. Nearly everyone knows that they need good documentation, and most people try to create good documentation. And most people fail. Usually, it’s not because they don’t try hard enough. Usually, it’s because they are not doing it the right way.

This system is a way to make your documentation better, not by working harder at it, but by doing it the right way. The right way is the easier way – easier to write, and easier to maintain.

[…]

It’s not actually a secret and it certainly shouldn’t be: documentation needs to include and be structured around its four different functions: tutorials, how-to guides, technical reference and explanation. Each of them requires a distinct mode of writing. People working with software need these four different kinds of documentation at different times, in different circumstances – so software usually needs them all, and they should all be integrated into your documentation.

And documentation needs to be explicitly structured around them, and they all must be kept separate and distinct from each other.

Tutorials

How-to guides

Reference

Explanation

oriented to

learning

a goal

information

understanding

must

allow the newcomer to get started

show how to solve a specific problem

describe the machinery

explain

its form

a lesson

a series of steps

dry description

discursive explanation

analogy

teaching a small child how to cook

a recipe in a cookery book

a reference encyclopedia article

an article on culinary social history