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:

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

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

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

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

## Related Concepts

Our event sourcing approach is part of our broader CQRS (Command Query
Responsibility Segregation) architecture. Understanding event sourcing
helps explain:

- Why our read models are eventually consistent
- How we achieve audit logging "for free"
- Why replaying events is central to our testing strategy

For more on CQRS, see [Understanding Our Architecture](/concepts/cqrs-architecture).

Components for Explanations

Diagrams and Visuals

Explanations benefit heavily from visual aids:

## System Architecture

The following diagram shows how requests flow through the system:

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

The load balancer distributes traffic across API gateway instances...

Comparison Tables

Tables work well for comparing approaches:

## Comparing Approaches

| Aspect | Monolith | Microservices |
|--------|----------|---------------|
| Deployment | Single unit, simpler | Independent, more complex |
| Scaling | Vertical | Horizontal per service |
| Team autonomy | Lower | Higher |
| Operational overhead | Lower | Higher |

We chose microservices because team autonomy was critical for our
100+ engineer organization...

Callouts for Key Insights

<Note>
This is a common source of confusion: the "eventual" in eventual consistency
doesn't mean "maybe" - it means "not immediately, but guaranteed eventually."
</Note>

<Warning>
This design assumes network partitions are rare. In environments with
unreliable networks, consider stronger consistency guarantees.
</Warning>

Expandable Sections for Depth

Use expandables for tangential but valuable details:

<Expandable title="Historical note: Why we migrated from Redis">
Our original implementation used Redis for caching. In 2023, we migrated
to a custom solution because...

This context exp