Documentation is the written knowledge that lets people use, operate and change software without asking its authors. It includes guides, API references, design notes, runbooks and comments. Docs rot when nobody owns them, so the best teams treat them like code: versioned, reviewed and tested.
Key concepts
- Four kinds of need: tutorials teach, how-to guides solve a task, references list facts, explanations give background.
- Docs as code: plain text in version control, reviewed in the same change as the code it describes.
- Findability: a good structure, search and links matter as much as the prose.
- Freshness: dates, owners and automated checks, such as running the examples, stop silent decay.
- Code comments: explain why, not what; the code already says what.
Vocabulary
- README: the first file a reader sees, saying what the project is and how to start.
- Runbook: step-by-step instructions for operating or recovering a system.
- Changelog: a human-readable list of changes between versions.
- Docstring: documentation written inside the source, next to a function or type.
What to study, in order
- Write a README that lets a stranger install and run your project in ten minutes.
- Keep your docs in the repository and review them in the same pull request as code.
- Generate an API reference from docstrings, then add the hand-written guide it needs.
- Write a runbook for one failure and have someone else follow it.
- Test the examples automatically so they cannot drift from the code.
Related tags
#technical-writing #api-design #version-control #open-source