documentation-writing

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

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

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

Creating a New Document

```markdown

# [Feature Name]

Brief one-sentence description of what this is.

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

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

Step-by-step setup with real examples.

Common use cases with runnable code.

Common problems and solutions.

```

Document Types (Diataxis)

| Type | Purpose | Location | User Question |

| ----------- | ------------- | ----------------- | ----------------------- |

| Tutorial | Learning | docs/tutorials/ | "Teach me how" |

| How-To | Doing | docs/howto/ | "Help me do X" |

| Reference | Information | docs/reference/ | "What are the options?" |

| Explanation | Understanding | docs/concepts/ | "Why is it this way?" |

Step 1: Determine Document Type

Ask: What is the reader trying to accomplish?

• Learning something new → Tutorial
• Solving a specific problem → How-To
• Looking up details → Reference
• Understanding concepts → Explanation

Step 2: Choose Location

```

docs/

├── tutorials/ # Learning-oriented

├── howto/ # Task-oriented

├── reference/ # Information-oriented

├── concepts/ # Understanding-oriented

└── index.md # Links to all docs

```

Step 3: Write with Examples

Every concept needs a runnable example:

```python

# Example: Analyze file complexity

from amplihack import analyze

result = analyze("src/main.py")

print(f"Complexity: {result.score}")

# Output: Complexity: 12.5

```

Step 4: Link from Index

Add entry to docs/index.md:

```markdown

• [New Feature Guide](./howto/new-feature.md) - How to configure X

```

Step 5: Validate

Checklist before completion:

• [ ] File in docs/ directory
• [ ] Linked from index or parent doc
• [ ] No temporal information
• [ ] All examples tested
• [ ] Follows one Diataxis type

When to Read Supporting Files

reference.md - Read when you need:

• Complete frontmatter specification
• Detailed Diataxis type definitions
• Markdown style conventions
• Documentation review checklist

examples.md - Read when you need:

• Full document templates for each type
• Real-world documentation examples
• Before/after improvement examples
• Complex documentation patterns

| Anti-Pattern | Why It's Bad | Better Approach |

| ------------------ | ------------- | ------------------------------ |

| "Click here" links | No context | "See [auth config](./auth.md)" |

| foo/bar examples | Not realistic | Use real project code |

| Wall of text | Hard to scan | Use headings and bullets |

| Orphan docs | Never found | Link from index |

| Status in docs | Gets stale | Use Issues/PRs |

When writing documentation BEFORE implementation (document-driven development):

````markdown

# [PLANNED - Implementation Pending]

This document describes the intended behavior of Feature X.

```python

# [PLANNED] - This API will be implemented

def future_function(input: str) -> Result:

"""Process input and return result."""

pass

```

````

Once implemented, remove the [PLANNED] markers and update with real examples.

```

---

Full reference: See [reference.md](./reference.md) for complete specification.

Templates: See [examples.md](./examples.md) for copy-paste templates.

```