documentation

# Documentation

Create clear, maintainable technical documentation.

## Documentation Types

```
┌─────────────────────────────────────────────────────────────┐
│                  DOCUMENTATION LANDSCAPE                     │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  README              API DOCS            ARCHITECTURE       │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │ First       │    │ Endpoint    │    │ ADRs        │     │
│  │ impression  │    │ reference   │    │ System      │     │
│  │ Quick start │    │ Examples    │    │ design      │     │
│  └─────────────┘    └─────────────┘    └─────────────┘     │
│                                                             │
│  USER GUIDES         CODE DOCS          DIAGRAMS           │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │ How-to      │    │ JSDoc       │    │ Mermaid     │     │
│  │ Tutorials   │    │ Inline      │    │ Architecture│     │
│  │ Workflows   │    │ comments    │    │ Flows       │     │
│  └─────────────┘    └─────────────┘    └─────────────┘     │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

## Selection Guide

| Type | When to Use | Audience |
|------|-------------|----------|
| README | Project entry point | All users |
| API Docs | Endpoint reference | Developers |
| ADR | Major decisions | Team/future devs |
| User Guide | Task completion | End users |
| Code Docs | Implementation | Contributors |

## Core Principles

### 1. Documentation as Code
Docs live with code, version with code, review with code.

```
✅ Docs in repo alongside source
✅ Markdown for portability
✅ Generated docs from source (OpenAPI, JSDoc)
✅ CI checks for doc freshness
```

### 2. Audience-First Writing
Write for who's reading, not what you know.

```
✅ README: "I just found this repo"
✅ API Do