Explanation
Explanation, or discussion, clarifies and illuminates a particular topic. It broadens the documentation’s coverage of a topic.
— diataxis.fr/explanation
Explanation is understanding-oriented. It exists to broaden context — why choices were made, how the system behaves under the hood, what assumptions
constrain the design. It does not give step-by-step instructions and it does not list APIs.
Authoring guidance
When adding an explanation to this section:
Free yourself from a concrete task. Discuss the topic in its own right.
Connect ideas. Cross-reference Reference for what and How-to guides for how.
Acknowledge trade-offs. Explanation is the place to say “we don’t do X because Y.”
Welcome multiple perspectives. Unlike reference, explanation can hold competing views and let the reader weigh them.