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.
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 |