Explanation is a discusive treatment of a subject, that permits reflection. Explanation is understanding-oriented.
Explanation deepens and broadens the reader's understanding of a subject. It brings clarity, light and context.
The concept of reflection is important. Reflection occurs after something else, and depends on something else, yet at the same time brings something new - shines a new light - on the subject matter.
The perspective of explanation is higher and wider than that of the other not types. It does not take the user's eye-level view, as in a how-to guide, or a close-up view of the machinery, like reference material. Its scope in each case is a topic - "an area of knowledge", that somehow has to be bounded in a reasonable, meaningful way.
For the user, explanation joins things together. It's an answer to the question: Can you tell me about ...?
It's documentation that it makes sense to read while away from the product itself (one could say, explanation is the only kind of documentation that it might make sense to read in the bath).
Explanation is characterised by its distance from the active concerns of the practitioner. It doesn't have direct implications for what they do, or for their 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
The word explanation - and its cognates in other languages - refer to unfolding, the revelation of what is hidden in the folds. So explanation brings to the light things that were implicit or obscured.
Similarly, words that mean understanding share roots in words meaning to hold or grasp (as in comprehend). That's an important part of understanding, to be able to hold something or be in possession of it. Understanding seals together the other components of our mastery of a craft, and makes it safely our own.
Understanding doesn't 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.
Quite often explanation is not explicitly recognised 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.
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.
Opinion might seem like a funny thing to introduce into documentation. The fact is that all human activity and knowledge is invested within opinion, with beliefs and thoughts. The reality of any human creation is rich with opinion, and that needs to be part of any understanding of it.
Similarly, any understanding comes from a perspective, a particular stand-point - which means that other perspectives and stand-points exist. Explanation can and must consider alternatives, counter-examples or multiple different approaches to the same question.
In explanation, 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 it tends to absorb other things. The writer, intent on covering the topic, feels the urge to include instruction or technical description related to it. But documentation already has other places for these, and allowing them to creep in interferes with the explanation itself, and removes them from view in the correct place.
- 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.
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's clearly not a book we would read while cooking. We would read when we want to reflect on cooking. It illuminates the subject by taking multiple different perspectives on it, shining light from different angles.
After reading a book like On food and cooking, our understanding is changed. Our knowledge is richer and deeper. What we have learned may or may not be immediately applicable next time we are doing something in the kitchen, but it will change how we think about our craft, and will affect our practice.