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](../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:

```markdown
---
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
```

## 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.

```markdown
<!-- Good: Relatable analogy -->
Think of the message queue like a post office. Messages (letters) are dropped off
by senders and held until recipients pick them up. The post office doesn't care
about the content - it just ensures reliable delivery.

<!-- Avoid: Jumping straight to technical details -->
The message queue implements a FIFO buffer with configurable persistence
and at-least-once delivery semantics.
```

### Explain the "Why" Behind Design Decisions

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

```markdown
<!-- Good: Explains rationale -->
We chose eventual consistency over strong consistency because our read-heavy
workload (100:1 read-to-write ratio) benefits more from low latency than from
immediate consistency. Most users never notice the brief delay.

<!-- Avoid: Just states facts -->
The system uses eventual consistency with a 500ms propagation window.
```

### Discuss Trade-offs Honestly

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

```markdown
## Trade-offs

This architecture optimizes for **write throughput** at the cost of:

- **Read latency**: Queries may need to hit multiple partitions
- **Complexity**: Developers must understand partition keys
- **Cost**: More storage due to denormalization

This trade-off makes sense for our use case (high-volume event ingestion)
but may not suit read-heavy analytics workloads.
```

### 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'