Explanation is discussion that clarifies and illuminates a particular topic. Explanation is understanding-oriented.
Explanation clarifies, deepens and broadens the reader’s understanding of a subject.
It's not concerned with what the user might be doing, like tutorials and how-to guides. It's not a close-up view of the machinery, like reference material. It's documentation that approaches a topic from a higher perspective, and from different angles.
This allows explanation to become discussion, a more relaxed, freer way to consider something. Explanation joins things together. It's documentation that it makes sense to read while away from the product itself.
Explanation, unlike the other three forms of documentation, doesn't have a direct part in a user's practice or work. This means that it's sometimes seen as being of lesser importance. That's a mistake; it may be less urgent than the other three, but it's no less important. It's not a luxury. No practitioner of a craft can afford to be without an understanding of that craft, and needs the explanatory material that will help weave it together.
Explanation by any other name
Your explanation documentation doesn't need to be called Explanation. Alternatives include:
- Discussion
- Background
- Conceptual guides
- Topics
In most European languages, words that mean understanding share roots in words meaning to hold or grasp. That's an important part of understanding, to be able to hold something or be in possession of it. It seals together the other components of our mastery of a craft, and makes it safely our own.
Understanding doesn't simply come from explanation, but explanation is required to form that web that helps hold everything together. Without it, the practitioner's knowledge of their craft is loose and fragmented and fragile, and their exercise of it is anxious.
It's fairly rare to see explanation given its own section in documentation, and the idea that things need to be explained is often only faintly expressed. Instead, explanation tends to be scattered in small parcels in other sections.
It's not always easy to write good explanatory material. Where does one start? It's also not clear where to conclude. There is an open-endedness about it that can give the writer too many possibilities.
Tutorials, how-to-guides and reference are all clearly defined in their scope by something that is also well-defined: by what you need the user to learn, what task the user needs to achieve, or just by the scope of the machine itself.
In the case of explanation, it's useful to have a real or imagined why question to serve as a prompt. Otherwise, you simply have to draw some lines that mark out a reasonable area and be satisfied with that.
In 1984 Harold McGee published On food and cooking.
The book doesn't teach how to cook anything. It doesn't contain recipes (except as historical examples) and it isn't a work of reference. Instead, it places food and cooking in the context of history, society, science and technology. It explains for example why we do what we do in the kitchen and how that has changed.
It considers its subject from multiple different perspectives, using them to illuminate it in different ways.
After reading a book like On food and cooking, our understanding is changed. Our knowledge is richer and deeper. We may not have learned anything that we can apply in practice, or that will change what we do, but it will change how we think about our craft, and that is just as valuable.
It's something we might read at our leisure, away from the kitchen itself, when we want to think about cooking at a higher level, and to understand more about the subject.
When writing explanation you are helping to weave a web of understanding for your readers. Make connections to other things, even to things outside the immediate topic, if that helps.
Provide background and context in your explanation: explain why things are so - design decisions, historical reasons, technical constraints - draw implications, mention specific examples.
Things to discuss
- the bigger picture
- history
- choices, alternatives, possibilities
- why: reasons and justifications
Explanation guides are about a topic in the sense that they are around it. Even the names of your explanation guides should reflect this; you should be able to place an implicit (or even explicit) about in front of each title. For example: About user authentication, or About database connection policies.
Explanation can consider alternatives, counter-examples or multiple different approaches to the same question. You're not giving instruction or describing facts - you're opening up the topic for consideration. It helps to think of explanation as discussion: discussions can even consider and weigh up contrary opinions.
One risk of explanation is that other things can tend to creep in. Explanation should do things that the other parts of the documentation do not. It’s not the place of an explanation to instruct the user in how to do something. Nor should it provide technical description. These functions of documentation are already taken care of in other sections.
- The reason for x is because historically, y...
- Explain.
- W is better than z, because...
- Offer judgements and even opinions where appropriate..
- An x in system y is analogous to a w in system z. However...
- Provide context that helps the reader.
- Some users prefer w (because z). This can be a good approach, but...
- Weigh up alternatives.
- An x interacts with a y as follows:...
- Unfold the machinery's internal secrets, to help understand why something does what it does.