> ## Documentation Index > Fetch the complete documentation index at: https://mcp-b-sync-npm-packages-docs-bf03420.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Explanation # Explanation¶ Explanation is a discursive 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. Explanation - understanding oriented, theoretical knowledge, that serves our study 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 three 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). *** ## The value and place of explanation¶ ### Explanation and understanding¶ 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*. ### Explanation and its boundaries¶ 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. *** ## Writing good explanation¶ ### Make connections¶ 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 context¶ **Provide background and context in your explanation**: explain *why* things are so - design decisions, historical reasons, technical constraints - draw implications, mention specific examples. ### Talk *about* the subject¶ 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*. ### Admit opinion and perspective¶ 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*. ### Keep explanation closely bounded¶ 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 language of explanation¶ \*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. *** ## Analogy from food and cooking¶ In 1984 [Harold McGee](https://www.curiouscook.com) 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*.