diataxis-explanationlisted

Write a Diataxis explanation — an understanding-oriented discussion that illuminates the why behind a topic, its background, design rationale, trade-offs, history, and connections to other ideas. Use when the reader needs to grasp a concept or decision, not perform a task or look up a fact. Anti-trigger; for accomplishing a known task use diataxis-how-to, for a beginner learning by doing use diataxis-tutorial, for fact lookup use diataxis-reference.
modeled-information-format/mif-docs-plugin · ★ 0 · Code & Development · score 71

Install: claude install-skill modeled-information-format/mif-docs-plugin

# diataxis-explanation Produces an **explanation** in the Diataxis sense: *understanding-oriented*. The reader wants to comprehend — to see why something is the way it is, how it connects to other ideas, and what the alternatives and trade-offs were. Success is the reader *understands*, not that they did something or found a value. An explanation is not a tutorial (it does not walk you through doing), not a how-to (it does not accomplish a task), and not reference (it does not catalog facts) — keep those modes out. ## Pattern (industry: Diataxis, diataxis.fr) 1. **Topic title** — names the subject under discussion, framed as understanding: "Understanding X", "Why we use Y", "The thinking behind Z". Not "How to…". 2. **Framing** — open by naming the question or tension the reader is here to resolve, and why it matters. Set the boundaries of the discussion. 3. **Discursive body** — flowing prose that supplies background, context, and the design rationale. Trace history, surface trade-offs, and weigh the alternatives that were *not* chosen and why. 4. **Connections** — relate the topic to adjacent ideas, decisions, and parts of the system so the reader sees where it fits. 5. **Closing perspective** — a short synthesis of what the reader now understands; point to how-to/reference/tutorial for doing or looking up. ## Rules that keep it an explanation - Discuss, don't instruct. No numbered procedure of imperative steps — that is a tutorial or how-to. If you