What nobody tells you about documentation

However hard you work on documentation, it won't work for your software - unless you do it the right way.They are: tutorials, how-to guides, explanation and technical reference. They seem to be a secret, though they shouldn’t be.If you can put these principles into practice, it will make your documentation better and your project, product or team more successful - that’s a promise.Documentation needs to include and be structured around its four different functions: tutorials, how-to guides, explanation and technical reference. People working with software need these four different kinds of documentation at different times, in different circumstances - so software usually needs them all.And documentation needs to be explicitly structured around them, and they all must be kept separate and distinct from each other.A tutorial:Analogy: teaching a small child how to cookA how-to guide:Analogy: a recipe in a cookery bookAn explanation:Analogy: an article on culinary social historyA reference guide:Analogy: a reference encyclopaedia articleThis division makes it obvious to both author and reader what information goes where. The demands of each kind are different from those of the others, so any attempt at documentation that fails to maintain this structure suffers, as it’s pulled in different directions at once.Once you understand the structure, it becomes a very useful tool for analysing existing documentation, and understanding what needs to be done to improve it.You may well ask: where do things like changelogs, contribution policies, and other information about the project fit into this scheme? It doesn’t matter: right now, your learner does not need to know about those in order to make progress.How-to guides take the reader through the steps required to solve a real-world problem.They are recipes, directions to achieve a specific end - for example: how to create a web form; how to plot a three-dimensional data-set; how to enable LDAP authentication.They are wholly goal-oriented.If you'd like an analogy, think about a recipe, for preparing something to eat.A recipe has a clear, defined end. As in tutorials, detailed explanations are out of place here.A how-to guide must address a specific question or problem: How do I …?This is one way in which how-to guides are distinct from tutorials: when it comes to a how-to guide, the reader can be assumed to know what they should achieve, but don’t yet know how - whereas in the tutorial, you are responsible for deciding what things the reader needs to know about.A how-to guide should not explain things. Sometimes, the section exists, but has a name such as Background or Other notes and doesn't really do justice to the function.Discussions are less easy to create than it might seem - things that are straightforward to explain when you have the starting-point of someone’s question are less easy when you have a blank page and and have to write down something about it.A topic isn’t defined by a specific task you want to achieve, like a how-to guide, or what you want the user to learn, like a tutorial. These functions of documentation are already taken care of in other sections.This structure is clear, and it works, but there is a reason why it's not so obvious, and that is the way the characteristics of each quadrant of the documentation overlap with those of its neighbours in the scheme.Tutorials and how-to guides are similar because they are both concerned with describing practical steps, while what how-to guides share with technical referenceis that they’re what we need when we are actually at work, coding. Reference guides and explanation are similar because they’re concerned with theoretical knowledge, and finally, what tutorials have in common with explanation is that they are most useful when we are studying, rather than actually working:  Given these overlaps, it's not surprising that the different kinds of documentation become confused and mixed in with each other.Though it's rare to find it clear examples of it used fully, a great deal of documentation recognises, in different ways, each of these four functions.Some projects do adopt it fully, including Django (though this wasn't made explicit in earlier versions), and django CMS. It becomes much clearer what to write, how to write it, and where to put it.It serves users better, because for all the different phases in the cycle of their interaction with the software they will find the right kind of documentation, that serves the needs of that moment.Writing documentation that explicitly and distinctly addresses each of the four quadrants helps the software attract and keep more users, who will use it more effectively - and that is one of the things the creators of software want most of all.Our experts really do deserve the name.