explanation-docs

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.

Dependency: Use this skill with docs-style for core writing principles. To confirm explanation is the right type — rather than a tutorial, how-to, or reference — see docs-style/references/diataxis-compass.md.

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:

---
title: "[Concept/System Name] Explained"
description: "Understand how [concept] works and why it was designed this way"
---

# Understanding [Concept]

Brief intro (2-3 sentences): What this document explains and why it matters. Set expectations for what the reader will understand after reading.

## Overview

High-level summary of the concept. What is it? What problem does it solve? This should be understandable without deep technical knowledge.

## Background and Context

### The Problem

What situation or challenge led to this design? What were users or developers struggling with?

### Historical Context

How did we get here? What came before? This helps readers understand why alternatives were rejected or why certain constraints exist.

## How It Works

### Core Concepts

Explain the fundamental ideas. Use analogies to connect to concepts readers already understand.

<Note>
Use diagrams or visual aids when explaining complex relationships or flows.
</Note>

### The Mechanism

Walk through how the system actually operates. This is conceptual, not procedural - explain the "what happens" rather than "what to do."

### Key Components

Break down the major parts and how they interact. For each component:
- What role does it play?
- How does it relate to other components?

## Design Decisions and Trade-offs

### Why This Approach?

Explain the reasoning behind key design choices. What goals drove these decisions?

### Trade-offs Made

Every design involves trade-offs. Be explicit about:
- What was prioritized
- What was sacrificed
- Under what conditions this design excels or struggles

### Constraints and Assumptions

What constraints shaped the design? What assumptions does it rely on?

## Alternatives Considered

### [Alternative Approach 1]

Brief description of an alternative approach. Why wasn't it chosen? Under what circumstances might it be better?

### [Alternative Approach 2]

Another alternative. Comparing alternatives helps readers understand the design space.

## Implications and Consequences

What does this design mean for:
- Performance?
- Scalability?
- Developer experience?
- Future extensibility?

## Related Concepts

- [Related Concept 1](/concepts/related-1) - How it connects to this topic
- [Related Concept 2](/concepts/related-2) - Another related area
- [Deeper Technical Reference](/reference/detail) - For implementation specifics