Diátaxis Explanation Quadrant

Parent: Writing and Documentation · researched 2026-05-29T19:02:15.397Z· 6 sources · 10 concepts · skill explanation-doc-writing

An explanation doc is a discussion. Its purpose is not to instruct, not to enumerate, and not to walk a reader through a goal. Its job is to leave the reader with a clearer mental model — of why the s

Overview

An explanation doc is a discussion. Its purpose is not to instruct, not to enumerate, and not to walk a reader through a goal. Its job is to leave the reader with a clearer mental model - of why the system is shaped this way, what alternatives existed, what trade-offs were made. [source]
The single most-violated rule: explanation is not a proposal. It describes the world as it is - choices already made, designs already shipped, reasoning already settled. If you are arguing for a change, you are writing an RFC, not an explanation. [source]

1. The reader's question is "why", not "how" or "what"

If the reader's question is "how do I configure replication factor", they need a how-to. Explanation answers the shape-of-the-world questions. [source]

2. Build the mental model, then layer the detail

Lead with the analogy or the one-sentence essence. "Think of the write-ahead log as a journal: every change is written there first, and only later applied to the data files." Then add the next layer: "This means a crash in the middle of an update never leaves the data file half-written." [source]

3. Show alternatives and why they were not chosen

A decision without alternatives is not a decision; it's a proclamation. The explanation doc names the roads not taken: "We considered an LSM-tree here, but the workload is read-heavy and the write-amplification penalty was not worth the write throughput gain." [source]

4. History earns trust

A short history paragraph - "v1 used Redis for the queue; we hit head-of-line blocking under load in 2024 and moved to Kafka in v2" - gives the reader context that no amount of current-state description can replicate. [source]

5. Discuss, don't prescribe

Explanation uses words like because, however, the trade-off is, one consequence is. It avoids do this, use this, configure this. [source]

7. Distinguish from RFCs and ADRs

RFC = proposing a change before it ships. Argumentative voice. Open to debate. [source]
ADR (Architecture Decision Record) = a small, dated note of a decision made. [source]
Explanation doc = the broader discussion of how and why the system is the way it is. [source]

8. Stay evergreen

Explanation docs should age slowly. Captures the durable reasoning: invariants, trade-offs, philosophy. [source]

AP-1 — The "explanation" that is secretly a tutorial

> "To understand caching, let's build a simple cache..." [source]
If the reader is creating files, you are running a tutorial. [source]

AP-2 — Prescriptive sneak-in

> "You should always set replication=3 because…" [source]
That's a how-to recommendation. Recast: "Replication factor 3 trades disk and write-bandwidth for the ability to tolerate single-node failure." [source]

AP-3 — No alternatives named

A doc that explains a choice without ever naming what was rejected reads as a sales pitch. [source]

AP-4 — Drift into RFC territory

Argumentative voice, open questions, "we are considering moving to…" - that's an RFC. [source]

References

Explanation - Diátaxis [source]
Explanation - Divio Documentation [source]
Michael Nygard, "Documenting Architecture Decisions" (2011) [source]

Children

Mental-model construction (frontier)
ADR pattern (frontier)
Decisions log (frontier)
Alternatives considered (frontier)
Discussion vs RFC vs runbook (frontier)

Frontier under this node: ADR pattern, Decisions log, Discussion vs RFC vs runbook, Mental-model construction

← the whole tree · 3D view· how to read this page