​

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 <topic>? - 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. 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.