Documentation Pro

Overview

Good documentation — accurate, findable, and maintained — is a force multiplier; bad documentation (missing, wrong, or rotting) is worse than none because it actively misleads. This skill covers writing docs developers actually use: READMEs that onboard, API docs that answer questions, ADRs that preserve decisions, runbooks that work at 3am, and the docs-as-code workflows that keep everything from rotting.

The through-line: docs are a product with users — write for their tasks, keep them next to the code.

When to use

• Writing a README for a new project or library.
• Documenting APIs, architectures, or operational procedures.
• Fixing documentation that's outdated, missing, or unused.
• Setting up docs-as-code workflows (linting, testing, publishing).
• Reviewing docs for clarity and accuracy.

Core concepts

• Docs for tasks, not topics. Organize by what users do: tutorials (learning), how-to guides (doing), reference (looking up), explanation (understanding) — the Diátaxis model. A README that's all reference and no quickstart fails new users; all tutorial and no reference fails experienced ones.
• README anatomy. What it is (one paragraph) → quickstart (copy-paste working in 5 minutes) → installation → basic usage → configuration → contributing → license. The quickstart is the whole game — if it doesn't work in 5 minutes, nothing else matters.
• API docs answer questions. For every endpoint/function: what it does, parameters (types, required, defaults, constraints), return shape, errors, and a working example. Generate reference from code (OpenAPI, JSDoc/TSDoc, rustdoc) so it can't drift; hand-write the guides and concepts.
• ADRs preserve decisions. Architecture Decision Records: context, options, decision, consequences, revisit triggers — one page, in the repo, next to the code. Future maintainers need the why, and "we discussed it in a meeting" is not preserved.
• Runbooks for 3am. Symptom → diagnosis steps → fix → verification → escalation. Tested (game days), linked from alerts, and written for a stressed, half-awake reader: commands copy-pasteable, no assumed context.
• Docs-as-code. Docs in version control, reviewed like code, built and published by CI, with linters (vale/proselint for prose, link checkers for rot) and tested examples (doctests, executable snippets). Docs that aren't built and checked rot silently.

Practical workflow

1. Identify the user and their task. New joiner onboarding? API consumer integrating? On-call diagnosing? Write for that task — one doc per task, not one doc per topic.
2. Start with the quickstart. Before comprehensive docs, make the 5-minute path work and document it. Test it from a clean environment — actually clean, not "clean except my setup."
3. Layer the docs. README (orient + quickstart) → guides (how-tos for common tasks) → reference (generated from code) → explanations/ADRs (concepts + decisions). Link between layers.
4. Write clearly. Short sentences, active voice, concrete examples over abstract description, prerequisites stated up front, and every code sample tested (CI runs them or they're lies waiting to happen).
5. Keep docs next to code. READMEs in the repo, API docs generated from annotations, ADRs in docs/adr/, runbooks in docs/runbooks/ linked from dashboards. Distance from code = rate of rot.
6. Maintain deliberately. Docs checklist in PR templates ("docs updated?"), link checking in CI, periodic audits (quarterly: is the quickstart still quick? are runbooks still accurate?), and delete docs that lie — wrong docs are worse than missing docs.

README template:

# Project Name
One-paragraph: what it does, who it's for.

## Quickstart
\`\`\`bash
# copy-paste, works in 5 minutes from clean machine
\`\`\`

## Installation
## Usage (common tasks with examples)
## Configuration
## API Reference (link to generated docs)
## Contributing
## License

Common pitfalls

• README as a novel. 500 lines before the first runnable command. Quickstart first, always — respect the reader's time.
• Untested examples. Code samples that don't run (drifted APIs, missing imports). Test every sample in CI or delete it — a broken example destroys trust instantly.
• Missing the why. Reference docs listing parameters without explaining when/why to use the thing. Concepts and guides carry the why; reference alone is a dictionary without definitions.
• Docs far from code. Wiki pages describing v2 while the code is on v4. Colocate, generate, and review docs with the code changes they describe.
• No onboarding path. Docs assume tribal knowledge ("just deploy it like usual"). Write for the new joiner — they're the documentation's most important user.
• Runbooks that don't run. Prose descriptions without copy-pasteable commands, untested since written. Game-day them: follow the runbook literally during a drill.
• Documenting everything equally. Exhaustive docs for trivial utils, nothing for the complex core. Document where confusion and cost concentrate: onboarding, tricky domains, operations.