Explanation Documentation Skill

This skill provides patterns for writing effective explanation documents. Explanations are understanding-oriented content for readers who want to know why things work the way they do.

Purpose & Audience

Target readers:

• - Users who want to understand concepts deeply, not just use them
• Architects and technical leads evaluating design decisions
• Team members onboarding to a codebase or system
• Anyone asking "why?" or "how does this work?"

Explanations are for reading away from the keyboard. Unlike tutorials or how-to guides, readers aren't trying to accomplish a task while reading. They're building mental models.

Explanations are NOT:

• - Tutorials (which teach through hands-on doing)
• How-To guides (which accomplish specific goals)
• Reference docs (which look up precise details)

Explanation Document Template

Use this structure for all explanation documents:

CODEBLOCK0

Writing Principles

Focus on Understanding, Not Doing

Explanations answer "why?" and "how does it work?" rather than "how do I?"

Explanation (good)	How-To (wrong context)
"The cache uses LRU eviction because memory is limited and recent items are more likely to be accessed again."	"To configure the cache, set the maxSize parameter."
"Authentication tokens expire to limit the damage if they're compromised."

"Refresh your token by calling the /refresh endpoint." |

Use Analogies and Mental Models

Connect unfamiliar concepts to things readers already know.

CODEBLOCK1

Explain the "Why" Behind Design Decisions

Don't just describe what exists - explain why it exists that way.

CODEBLOCK2

Discuss Trade-offs Honestly

Every design choice has costs. Acknowledging them builds trust and helps readers make informed decisions.

CODEBLOCK3

Structure for Reflection, Not Action

Explanations are read linearly, away from the keyboard. Structure them like essays, not manuals.

• - Use flowing prose more than bullet points
• Build concepts progressively - each section prepares for the next
• Allow for depth - it's okay if sections are longer than in how-to guides
• Include context that would be distracting in task-focused docs

Connect to the Bigger Picture

Show how this concept relates to other parts of the system or to broader industry patterns.

CODEBLOCK4

Components for Explanations

Diagrams and Visuals

Explanations benefit heavily from visual aids:

CODEBLOCK5mermaid
graph LR
A[Client] --> B[Load Balancer]
B --> C[API Gateway]
C --> D[Service A]
C --> E[Service B]
D --> F[(Database)]
E --> F
CODEBLOCK6

Comparison Tables

Tables work well for comparing approaches:

CODEBLOCK7

Callouts for Key Insights

CODEBLOCK8

Expandable Sections for Depth

Use expandables for tangential but valuable details:

CODEBLOCK9

Example Explanation Document

CODEBLOCK10

Checklist for Explanations

Before publishing, verify:

• - [ ] Title indicates this explains a concept (not a how-to)
• [ ] Introduction sets expectations for what reader will understand
• [ ] Background section provides context and history
• [ ] Core concepts explained with analogies or mental models
• [ ] Design decisions include rationale, not just facts
• [ ] Trade-offs discussed honestly
• [ ] Alternatives mentioned and compared
• [ ] Implications for different concerns addressed
• [ ] Related concepts linked
• [ ] Written for reading away from keyboard (no tasks to follow)
• [ ] Progressive structure builds understanding step by step

When to Use Explanation vs Other Doc Types

Reader's Question	Doc Type	Focus
"How do I do X?"	How-To Guide	Steps to accomplish a goal
"Teach me about X"

Tutorial | Learning through guided doing | | "What is the API for X?" | Reference | Precise technical details | | "Why does X work this way?" | Explanation | Understanding and context | | "What are the trade-offs of X?" | Explanation | Design rationale | | "How does X relate to Y?" | Explanation | Conceptual connections |

Explanation Signals

Write an explanation when users:

• - Ask "why" questions
• Need to make architectural decisions
• Are evaluating whether something fits their use case
• Want to understand design philosophy
• Need context before diving into implementation

Not an Explanation

If users need to accomplish something while reading, it's not an explanation:

• - "How to configure caching" - How-To Guide
• "Cache API reference" - Reference Doc
• "Build a caching layer tutorial" - Tutorial
• "How caching works and why we use LRU" - Explanation

Related Skills

• - docs-style: Core writing conventions and components
• howto-docs: How-To guide patterns for task-oriented content
• reference-docs: Reference documentation patterns for lookups
• tutorial-docs: Tutorial patterns for learning-oriented content