> ## 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. # Reference explanation # The difference between reference and explanation¶ Explanation and reference both belong to the *theory* half of the Diátaxis map - they don’t contain steps to guide the reader, they contain theoretical knowledge. The difference between them is - just as in the difference between tutorials and how-to guides - the difference between the *acquisition* of skill and knowledge, and its *application*. In other words it’s the distinction between *study* and *work*. ## A straightforward distinction, *mostly*¶ Mostly it’s fairly straightforward to recognise whether you’re dealing with one or the other. *Reference*, as a form of writing, is well understood; it’s used in distinctions we make about writing from an early age. In addition, examples of writing are themselves often clearly one or the other. A tidal chart, with its tables of figures, is clearly reference material. An article that explains *why* there are tides and how they behave is self-evidently explanation. There are good rules of thumb: * **If it’s boring and unmemorable** it’s probably *reference*. * **Lists of things** (such as classes or methods or attributes), and **tables of information**, will generally turn out to belong in *reference*. * On the other hand **if you can imagine reading something in the bath**, probably, it’s *explanation* (even if really there is no accounting for what people might read in the bath). Imagine asking a friend, while out for a walk or over a drink, **Can you tell me more about ``?** - the answer or discussion that follows is most likely going to be an *explanation* of it. ### … but intuition isn’t reliable enough¶ Mostly we can rely safely on intuition to manage the distinction between reference and explanations. But only *mostly* - because it’s also quite easy to slip between one form and the other. It usually happens while writing reference material that starts to become expansive. For example, it’s perfectly reasonable to include illustrative examples in reference (just as an encyclopaedia might contain illustrations) - but examples are fun things to develop, and it can be tempting to develop them into explanation (using them to say *why*, or show *what if*, or how it came to be). As a result one often finds explanatory material sprinkled into reference. This is bad for the reference, interrupted and obscured by digressions. But it’s bad for the explanation too, because it’s not allowed to develop appropriately and do its own work. ## Work and study¶ The real test, though, if we’re in doubt about whether something is supposed to be reference or explanation is: is this something someone would turn to while working, that is, while actually getting something done, executing a task? Or is it something they’d need once they have stepped away from the work, and want to think about it? These are two very fundamentally different *needs* of the reader, that reflect how, at that moment, the reader stands in relation to the craft in question, in a relationship of *work* or *study*. To help avoid being misled by intuition, see [The compass](../compass/#compass). **Reference** is what a user needs in order help *apply* knowledge and skill, while they are working. **Explanation** is what someone will turn to to help them *acquire* knowledge and skill - “study”. Understanding those two relationships and responding to the needs in them is the key to creating effective reference and explanation.