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