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.

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