documentation-writing

# Documentation Writing Skill

## Purpose

Creates high-quality, discoverable documentation following the Eight Rules and Diataxis framework. Ensures all docs are properly located, linked, and contain real runnable examples.

## When I Activate

I load automatically when you mention:

- "write documentation" or "create docs"
- "document this feature/module/API"
- "create a README" or "write a tutorial"
- "explain how this works"
- Any request to create markdown documentation

## Core Rules (MANDATORY)

### The Eight Rules

1. **Location**: All docs in `docs/` directory
2. **Linking**: Every doc linked from at least one other doc
3. **Simplicity**: Plain language, remove unnecessary words
4. **Real Examples**: Runnable code, not "foo/bar" placeholders
5. **Diataxis**: One doc type per file (tutorial/howto/reference/explanation)
6. **Scanability**: Descriptive headings, table of contents for long docs
7. **Local Links**: Relative paths, context with links
8. **Currency**: Delete outdated docs, include update metadata

### What Stays OUT of Docs

**Never put in `docs/`:**

- Status reports or progress updates
- Test results or benchmarks
- Meeting notes or decisions
- Plans with dates
- Point-in-time snapshots

**Where temporal info belongs:**

- Test results → CI logs, GitHub Actions
- Status updates → GitHub Issues
- Progress → Pull Request descriptions
- Decisions → Commit messages

## Quick Start

### Creating a New Document

```markdown
# [Feature Name]

Brief one-sentence description of what this is.

## Quick Start

Minimal steps to get started (3-5 steps max).

## Contents

- [Configuration](#configuration)
- [Usage](#usage)
- [Troubleshooting](#troubleshooting)

## Configuration

Step-by-step setup with real examples.

## Usage

Common use cases with runnable code.

## Troubleshooting

Common problems and solutions.
```

### Document Types (Diataxis)

| Type        | Purpose       | Location          | User Question           |
| ----------- | ------------- |