documentation

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