Diataxis Explanation

The Diataxis “Explanation” mode - oriented toward understanding rather than action, building a conceptual model for the reader.

Diataxis Explanation

Diataxis (from Daniele Procida’s framework) distinguishes four modes of documentation: tutorial (learning by doing), how-to (achieving a goal), reference (looking things up), and explanation (understanding why things are the way they are). The explanation mode is the one most often missing from technical writing - and the one that makes the other three make sense.

An explanation piece does not tell you how to do something. It tells you what something is, why it was designed this way, what tradeoffs were made, how it relates to other concepts. It is the mode that builds the mental model that makes how-to guides navigable. Without explanation, readers follow steps without understanding; they succeed when the steps apply and fail when the situation varies.

Explanation is oriented toward understanding, not action. A good explanation piece could be read with no intention of ever using the described system. It is interesting in itself.

Structural conventions

Does not contain steps or procedures (those belong in how-to or tutorial)
Does contain “why” reasoning: design decisions, tradeoffs, origins
Builds concepts in order: simpler before complex
Makes relationships explicit: “X relates to Y because…”

When to use

Concept docs, architecture explanations, “why does X work this way” posts, onboarding to a new domain, design system rationale.

When not to use

When the reader needs to accomplish a specific task right now. Runbooks, operational guides, reference documentation.

Pairs well with

friendly-mentor, candid, warm, blog-post-long-form

Often confused with

comparison-contrast: Comparison-contrast requires at least two subjects measured against each other. Diataxis explanation examines a single subject in depth to build understanding.

Instruction

Write in Diataxis explanation mode. Your goal is understanding, not action - do not include steps
or procedures. Build the reader's mental model: explain what it is, why it is designed this way,
what tradeoffs were made, how it relates to other concepts. Use the word "because" frequently.
Make relationships explicit. Build from simpler concepts to complex ones. The piece should be
interesting to read even by someone who never intends to use the described system.

Examples

Why Async Standups Work the Way They Do

An async standup is not a standup without the video call. It is a different kind of coordination mechanism, built on different assumptions about when and how information should move.

To understand why the distinction matters, it helps to understand what a standup is actually trying to accomplish. The daily standup has two functions that usually coexist in the same meeting without being separated: status visibility (who is doing what, what is blocked) and team cohesion (the daily ritual of shared presence, the sense of a team operating together). Synchronous standups do both at once because everyone is in the room at the same time. Async standups separate them.

The status-visibility function works differently in async format because information becomes persistent and addressable. In a synchronous standup, a blocker mentioned verbally reaches everyone in the room, but only for the duration of the sentence. The person who can resolve it must remember it, and the people who might have the same problem next must either have been present or get told separately. In an async channel, the same information is posted, searchable, and accessible to anyone on the team regardless of timezone or work schedule. The blocker reaches the right person not because they were present but because they are mentioned directly.

The team-cohesion function does not transfer to async in the same way, and this is why async-only teams sometimes feel fragmented. Daily synchronous standups create what anthropologists call “phatic communion” - interaction whose function is social bonding rather than information transfer. “How’s it going?” is not a request for information; it is a gesture of acknowledgment. Async updates can approximate some of this through informal additions to the update template, but a Slack thread is not a room. The teams that sustain cohesion in async-first environments almost always supplement their async standup with a different synchronous ritual - a weekly working session, a monthly retrospective - that exists specifically for the cohesion function that async cannot provide.

The reason async standups often produce higher-quality status information than synchronous ones is cognitive: writing forces more clarity than speaking. A person who says “working on the auth refactor” in a standup has technically satisfied the format. A person writing the same update often notices the vagueness before they post it and adds the detail that makes it useful. The act of writing creates a moment of reflection that verbal turn-taking does not.

Diataxis Explanation