# Diátaxis Explanation Quadrant > 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 Parent: [Writing and Documentation](https://llms-explorer.com/tree/writing-and-documentation/) · 17 facets · 34 facts · page: https://llms-explorer.com/tree/di-taxis-explanation-quadrant/ ## 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](https://llms-explorer.com/sources/mdb-context-hub/explanation-doc-writing/#overview) - 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](https://llms-explorer.com/sources/mdb-context-hub/explanation-doc-writing/#overview) ## 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](https://llms-explorer.com/sources/mdb-context-hub/explanation-doc-writing/#1-the-readers-question-is-why-not-how-or-what) ## 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](https://llms-explorer.com/sources/mdb-context-hub/explanation-doc-writing/#2-build-the-mental-model-then-layer-the-detail) ## 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](https://llms-explorer.com/sources/mdb-context-hub/explanation-doc-writing/#3-show-alternatives-and-why-they-were-not-chosen) ## 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](https://llms-explorer.com/sources/mdb-context-hub/explanation-doc-writing/#4-history-earns-trust) ## 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](https://llms-explorer.com/sources/mdb-context-hub/explanation-doc-writing/#5-discuss-dont-prescribe) ## 7. Distinguish from RFCs and ADRs - RFC = proposing a change before it ships. Argumentative voice. Open to debate. — [source](https://llms-explorer.com/sources/mdb-context-hub/explanation-doc-writing/#7-distinguish-from-rfcs-and-adrs) - ADR (Architecture Decision Record) = a small, dated note of a decision made. — [source](https://llms-explorer.com/sources/mdb-context-hub/explanation-doc-writing/#7-distinguish-from-rfcs-and-adrs) - Explanation doc = the broader discussion of how and why the system is the way it is. — [source](https://llms-explorer.com/sources/mdb-context-hub/explanation-doc-writing/#7-distinguish-from-rfcs-and-adrs) ## 8. Stay evergreen - Explanation docs should age slowly. Captures the durable reasoning: invariants, trade-offs, philosophy. — [source](https://llms-explorer.com/sources/mdb-context-hub/explanation-doc-writing/#8-stay-evergreen) ## AP-1 — The "explanation" that is secretly a tutorial - > "To understand caching, let's build a simple cache..." If the reader is creating files, you are running a tutorial. — [source](https://llms-explorer.com/sources/mdb-context-hub/explanation-doc-writing/#ap-1-the-explanation-that-is-secretly-a-tutorial) ## AP-2 — Prescriptive sneak-in - > "You should always set replication=3 because…" That's a how-to recommendation. Recast: "Replication factor 3 trades disk and write-bandwidth for the ability to tolerate single-node failure." — [source](https://llms-explorer.com/sources/mdb-context-hub/explanation-doc-writing/#ap-2-prescriptive-sneak-in) ## AP-3 — No alternatives named - A doc that explains a choice without ever naming what was rejected reads as a sales pitch. — [source](https://llms-explorer.com/sources/mdb-context-hub/explanation-doc-writing/#ap-3-no-alternatives-named) ## AP-4 — Drift into RFC territory - Argumentative voice, open questions, "we are considering moving to…" - that's an RFC. — [source](https://llms-explorer.com/sources/mdb-context-hub/explanation-doc-writing/#ap-4-drift-into-rfc-territory) ## References - Explanation - Diátaxis — [source](https://llms-explorer.com/sources/mdb-context-hub/explanation-doc-writing/#references) - Explanation - Divio Documentation — [source](https://llms-explorer.com/sources/mdb-context-hub/explanation-doc-writing/#references) - Michael Nygard, "Documenting Architecture Decisions" (2011) — [source](https://llms-explorer.com/sources/mdb-context-hub/explanation-doc-writing/#references) ## Where this helps - Writing the "why" section of a design doc where a reader needs the reasoning and tradeoffs behind a decision, not another set of instructions. — [source](https://llms-explorer.com/tree/di-taxis-explanation-quadrant/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - Deciding that a "how it works" page you're drafting is drifting into becoming a tutorial or reference and needs to be split into a separate document. — [source](https://llms-explorer.com/tree/di-taxis-explanation-quadrant/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - Onboarding a new engineer who needs the mental model behind a system — why it's built this way — rather than a step-by-step task list. — [source](https://llms-explorer.com/tree/di-taxis-explanation-quadrant/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - Writing documentation for a design decision that will be revisited later, where naming the alternatives considered and why they were rejected saves the next person from re-litigating the same debate. — [source](https://llms-explorer.com/tree/di-taxis-explanation-quadrant/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* ## How to apply this - Before writing, explicitly answer "what mental model am I trying to leave the reader with" — if you can't state it in a sentence, the doc isn't ready to be an explanation piece yet. — [source](https://llms-explorer.com/tree/di-taxis-explanation-quadrant/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - Name at least one alternative approach you didn't take and why, since this is what separates a genuine explanation from a one-sided pitch. — [source](https://llms-explorer.com/tree/di-taxis-explanation-quadrant/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - Keep the piece evergreen by describing durable reasoning — why this architecture, why this tradeoff — rather than a snapshot of current implementation details that will drift out of date. — [source](https://llms-explorer.com/tree/di-taxis-explanation-quadrant/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - Resist adding numbered steps or literal commands to an explanation doc — if the reader needs to actually do something, that content belongs in a how-to guide instead. — [source](https://llms-explorer.com/tree/di-taxis-explanation-quadrant/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* ## Antipatterns - Writing an "explanation" that is secretly a tutorial, walking the reader through numbered steps instead of building their mental model. — [source](https://llms-explorer.com/tree/di-taxis-explanation-quadrant/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - Sneaking prescriptive language ("you should", "always do this") into what's supposed to be a neutral discussion of tradeoffs. — [source](https://llms-explorer.com/tree/di-taxis-explanation-quadrant/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - Discussing a decision without naming any alternative that was considered, which makes the piece read as advocacy rather than explanation. — [source](https://llms-explorer.com/tree/di-taxis-explanation-quadrant/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - Letting an explanation doc drift into RFC territory by treating settled reasoning as an open proposal still seeking a decision. — [source](https://llms-explorer.com/tree/di-taxis-explanation-quadrant/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* ## Known issues - Explanation docs are the quadrant most likely to silently rot, since "durable reasoning" ages when the actual system's tradeoffs shift and nobody revisits the doc. — [source](https://llms-explorer.com/tree/di-taxis-explanation-quadrant/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - It's genuinely hard to keep an explanation neutral and discussion-oriented rather than prescriptive, especially when the author has a strong opinion about the "right" answer. — [source](https://llms-explorer.com/tree/di-taxis-explanation-quadrant/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - Readers looking for quick task completion will bounce off an explanation doc if they land on it expecting a how-to guide, so cross-linking between quadrants matters as much as the explanation's own quality. — [source](https://llms-explorer.com/tree/di-taxis-explanation-quadrant/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - Distinguishing an explanation from an RFC or ADR takes discipline — both discuss tradeoffs, but an RFC is a proposal seeking a decision while an explanation documents settled reasoning after the fact. — [source](https://llms-explorer.com/tree/di-taxis-explanation-quadrant/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* ## Context files - [Diátaxis Explanation Quadrant](https://llms-explorer.com/downloads/sources/mdb-context-hub/explanation-doc-writing.md)