system-overview-writer

# Explanation Documentation Skill

This skill provides guidelines for creating **explanation** documentation - understanding-oriented content about system architecture in the Diataxis framework.

## Purpose

Explanations help users **understand** concepts, architecture, and system design. They provide context and illuminate the "why" behind how things work.

## User Need

> "I want to understand how this system works."

## Characteristics

| Attribute | Description |
|-----------|-------------|
| **Orientation** | Understanding |
| **Focus** | Concepts and context |
| **Goal** | Illuminate and clarify |
| **Tone** | Thoughtful, discursive |

## Target Directory

Place explanations in: `docs/architecture/`

## Writing Guidelines

### DO

- Clarify and illuminate understanding
- Discuss alternatives and trade-offs
- Provide context and background
- Connect concepts to each other
- Explain the reasoning behind designs
- Be opinionated when appropriate
- Use diagrams to illustrate concepts

### DON'T

- Provide step-by-step instructions
- Focus on specific tasks
- Include code that needs to be copied
- Skip the "why" in favor of "what"
- Avoid taking positions

## Examples of Good Explanations

- "System Architecture Overview"
- "Authentication Architecture"
- "Data Flow in the Application"
- "Security Model"
- "Why We Chose PostgreSQL"

---

## Template

Use this template when creating architecture overview documentation:

```markdown
# [System/Component] Architecture

*Last updated: [YYYY-MM-DD]*

## Overview

[2-3 paragraphs providing a high-level description of the system, its purpose, and its place in the broader context]

## Key Concepts

### [Concept 1]

[Explanation of the concept, why it exists, and how it relates to the system]

### [Concept 2]

[Explanation]

### [Concept 3]

[Explanation]

## System Components

┌─────────────────────────────────────────────────────────┐
│                    [System Name]                         │
├─────────────┬─────────────