Documentation

---
name: Documentation
description: Technical documentation patterns, structure, maintenance, and avoiding common documentation failures.
metadata:
  category: writing
  skills: ["documentation", "technical-writing", "readme", "api-docs"]
---

## Structure Hierarchy

- README: what it is, how to install, quick example — 5 minutes to first success
- Getting Started: guided tutorial for beginners — one complete workflow
- Guides: task-oriented ("How to X") — goal-focused, not feature-focused
- Reference: exhaustive API/CLI docs — complete but not for learning
- Troubleshooting: common errors with solutions — search-optimized

## README Essentials

1. One-sentence description — what problem it solves
2. Installation — copy-paste command that works
3. Quick start — minimal example that actually runs
4. Link to full docs — don't cram everything in README

Missing any of these = users bounce before trying.

## Code Examples

- Every example must be tested — untested examples rot within months
- Show complete runnable code, not fragments — users copy-paste
- Include expected output — confirms they did it right
- Bad: `client.query(...)` / Good: full script with imports, setup, and output
- Version-pin examples: `npm install package@2.1.0` not `npm install package`

## API Documentation

- Every endpoint needs: method, path, parameters, request body, response, error codes
- Show real request/response bodies — not just schemas
- Include authentication in every example — most common missing piece
- Document rate limits and pagination upfront — not buried in footnotes
- Error responses need as much detail as success responses

## What Gets Outdated

- Screenshots — UI changes, screenshots don't
- Version numbers — hardcoded versions become wrong
- Links — external sites move, break constantly
- "Current" anything — write timelessly or add review dates
- Feature flags and experimental warnings — often forgotten after GA

## Maintenance Patterns

- Docs live next to code — same repo, same PR. Separate repos drift
- CI checks for broken links — `markdown-link-check` or equivalent
- Runnable examples as tests — if example breaks, build fails
- Review date in docs: "Last verified: 2024-01" — signals freshness
- Delete aggressively — outdated docs worse than no docs

## Common Failures

- Documenting implementation, not usage — users don't care how it works internally
- Assuming context — define acronyms, link prerequisites
- Wall of text — use headings, bullets, code blocks liberally
- "See X for more info" without link — friction kills follow-through
- Changelog as documentation — changes ≠ how to use current version

## Writing Style

- Imperative mood: "Run the command" not "You can run the command"
- Second person: "you" not "the user"
- Present tense: "This returns X" not "This will return X"
- Short sentences — one idea per sentence
- Active voice: "The function returns X" not "X is returned by the function"

## Searchability

- Use words users search for — not internal jargon
- Error messages verbatim in troubleshooting — users paste exact errors
- Multiple ways to describe same thing — alias common variations
- H2/H3 headings are SEO — match user queries
- Avoid clever titles — "Getting Started" beats "Your Journey Begins"

## Versioned Documentation

- Major versions need separate docs — v1 users shouldn't see v2 docs
- Migration guides between versions — step-by-step, not just changelog
- Default to latest stable, link to older versions
- Mark deprecated features clearly — don't just remove
- URL structure: `/docs/v2/` not query params

## README Anti-patterns

- Badge spam — 15 badges before content
- Massive feature lists — save for marketing page
- No installation instructions — assuming everyone knows
- Screenshots without context — what am I looking at?
- License-only README — legal compliance ≠ documentation