---
type: explanation
divio_category: understanding-oriented
target_audience: curious-users
purpose: conceptual-clarification
outcome: user-understands-why-and-how
---

# Explanation: {CONCEPT_OR_TOPIC}

> **Divio Type**: Explanation (Understanding-Oriented)
> **Target Audience**: Users who want to understand concepts and context
> **Purpose**: Clarify and illuminate to deepen understanding
> **Outcome**: User understands why things are the way they are

## Overview

{Introduce the concept/topic and why understanding it matters}

This explanation covers:

- {Key aspect 1 that will be discussed}
- {Key aspect 2 that will be discussed}
- {Key aspect 3 that will be discussed}

## Background and Context

{Provide historical context or background that helps frame the discussion}

**Why this matters**: {Explain relevance to users}

{Add diagram if it helps explain the concept}

![{Descriptive alt text}]({path-to-diagram})

## Core Concepts

### {Concept 1}

{Explain the concept in depth}

**Analogy**: {Use an analogy if it helps understanding}

**Why it works this way**: {Explain the reasoning}

**Implications**:

- {What this means for users}
- {How this affects behavior}
- {What to keep in mind}

### {Concept 2}

{Explain the next concept}

**Connection to {Concept 1}**: {How concepts relate}

### {Concept 3}

{Continue explaining key concepts}

## How It Works

{Explain the mechanism or process in detail}

**Step-by-step explanation**:

1. **{Phase 1}**: {What happens and why}
2. **{Phase 2}**: {What happens next and why}
3. **{Phase 3}**: {Continue the explanation}

{Use diagrams, flowcharts, or illustrations to clarify}

## Design Decisions

### Why {Decision/Approach} Was Chosen

**The problem**: {What needed to be solved}

**Considered alternatives**:

- **Option A**: {Description}
  - Pros: {Benefits}
  - Cons: {Drawbacks}
- **Option B**: {Description}
  - Pros: {Benefits}
  - Cons: {Drawbacks}
- **Chosen: Option C**: {Description}
  - Why this was chosen: {Reasoning}
  - Trade-offs accepted: {What was sacrificed for the benefits}

## Common Misconceptions

### Misconception: "{Common wrong belief}"

**Reality**: {What's actually true}

**Why the confusion**: {Why people think this}

**Clarification**: {Detailed explanation of the truth}

### Misconception: "{Another common wrong belief}"

**Reality**: {What's actually true}

**Example to illustrate**: {Concrete example that clarifies}

## Relationships and Connections

### Connection to {Related Concept}

{Explain how this concept relates to another}

**Differences**:

- {Key difference 1}
- {Key difference 2}

**Similarities**:

- {Key similarity 1}
- {Key similarity 2}

### Impact on {Related System/Feature}

{Explain how this concept affects other parts of the system}

## Trade-offs and Limitations

**Benefits of this approach**:

- {Benefit 1}
- {Benefit 2}
- {Benefit 3}

**Limitations**:

- {Limitation 1 and why it exists}
- {Limitation 2 and why it exists}

**When this might not be ideal**: {Scenarios where trade-offs are problematic}

## Practical Implications

### For {User Type 1}

{What this concept means for this type of user}

**Key takeaways**:

- {Actionable insight 1}
- {Actionable insight 2}

### For {User Type 2}

{What this concept means for this type of user}

## Further Reading

- **Tutorial**: Learn by doing with [Tutorial: {Topic}](../tutorials/{link})
- **How-To**: Apply this in practice with [How-To: {Task}](../how-to/{link})
- **Reference**: Technical details in [{Reference}](../reference/{link})
- **External**: [Article/Book about {Topic}]({external-link})

---

## Write the Docs Best Practices (Remove this section before publishing)

**Explanation Principles**:

- ✅ Understanding-oriented: Clarify and illuminate
- ✅ Discuss concepts, not tasks (not instructional)
- ✅ Provide context and background
- ✅ Explain "why" things are the way they are
- ✅ Discuss alternatives and trade-offs
- ✅ Make connections between ideas
- ✅ Can be more free-form than other types
- ✅ No imperative mood (not "do this")

**Accessibility**:

- ✅ Proper heading hierarchy
- ✅ Alt text for diagrams (especially important for conceptual diagrams)
- ✅ Clear language, define technical terms
- ✅ Use diagrams to clarify complex concepts
- ✅ Descriptive link text

**Inclusivity**:

- ✅ Diverse examples
- ✅ Gender-neutral language
- ✅ No cultural assumptions
- ✅ Consider different learning styles (visual, verbal, etc.)

**Explanation-Specific Guidelines**:

- Start with "why" before "what"
- Use analogies and metaphors to clarify
- Diagrams are very valuable for explanations
- Discuss design decisions and trade-offs
- Address common misconceptions
- Make connections to related concepts
- Don't just describe - explain and clarify
- Be conversational but accurate
