understand-doc-system

name	understand-doc-system
description	Get better understanding about the structure before writing documentation for a software or system. Invoke when asked/requested to plan on creating documentation.

The Documentation System

The Grand Unified Theory of Documentation

– David Laing

There is a secret that needs to be understood in order to write good software documentation: there isn't one thing called documentation, there are four.

They are: tutorials, how-to guides, technical reference and explanation. They represent four different purposes or functions, and require four different approaches to their creation. Understanding the implications of this will help improve most documentation - often immensely.

About the system

The documentation system outlined here is a simple, comprehensive and nearly universally-applicable scheme. It is proven in practice across a wide variety of fields and applications.

There are some very simple principles that govern documentation that are very rarely if ever spelled out. 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.

The system is widely adopted for large and small, open and proprietary documentation projects.

Introduction

The problem it solves

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.

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.

The 'secret'

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

This division makes it obvious to both author and reader what material, and what kind of material, goes where. It tells the author how to write, and what to write, and where to write it. It saves the author from wasting a great deal of time trying to wrestle the information they want to impart into a shape that makes sense, because each of these kinds of documentation has only one job.

In fact, it's extremely hard to maintain good documentation that doesn't implicitly or explicitly recognise the quadrants of this scheme. 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.

In the following sections, each of these four parts is dealt with in detail.

Making documentation work

For authors

One of the biggest headaches that documentation maintainers have to deal with is not having a clear picture of what they should be doing. They write and rewrite, but find it hard to make it fit together in satisfactory ways.

This structure resolves those questions by making clear distinctions and separations. They make documentation that is easier to write and maintain, that's easier to use and to find one's way around in.

The documentation doesn't write itself - but it's now possible to write it without also having to wrestle with poor fit, or unclear scope or doubt about what should be included or what style to adopt. It becomes much clearer what to write, how to write it, and where to put it.

For readers

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.

Quadrants

Check out the details of each quadrant from:

• Tutorials
• How-to guides
• Reference guides
• Explanation