Docs That Earn Their Keep
Good documentation is part of the software, not an afterthought. But not all docs are useful — the ones that get read and relied on are focused and purposeful. Three kinds earn their keep: a README to get started, API docs to integrate, and runbooks to operate. And one rule rules them all: bad, stale docs are worse than none, because they mislead.
The goal of documentation isn't to write a lot; it's to save the next person time and confusion — including future-you, who will have forgotten everything.
An appliance gives the parallel: a quick-start card to get going (README), the full specifications for anyone connecting to it (API docs), and a troubleshooting guide for when it misbehaves (runbook). Different docs for different needs.
README: The Front Door
A README is the front door to a project — usually the first file someone opens. A good one answers the basics fast: what this project is, how to run it, and where to look next. Its job is to get a new developer from "I just opened this" to "I have it running and I know my way around" with minimal friction. It's the single highest-value doc most projects have.
API Docs: The Contract
API docs describe how to use a piece of software's interface — the contract from Chapter 5. Anyone calling your code or service needs to know what to send and what they'll get back, and the API docs spell that out so they don't have to read your internals. Good API docs are what let other teams (and other companies) build on top of your software without talking to you first.
Runbooks: The Operating Manual
A runbook is a step-by-step procedure for operating and fixing the live system — "if reminders stop sending, do this; if the database fills up, do that". When something breaks at 2 AM (Chapter 11), the on-call engineer doesn't want to figure it out from scratch; they want a runbook that tells them exactly what to check and do. Runbooks turn hard-won operational knowledge into something anyone on the rotation can follow.
Docs That Stay True
The hardest part of docs is keeping them true. Outdated documentation actively misleads — it sends people down wrong paths with false confidence, which is worse than having nothing and knowing it. The fix is to keep docs close to the code and update them as part of the change, not as a someday chore. A small, current doc beats an exhaustive, stale one every time.
Cadence's docs earn their keep. Its README gets a new developer running in ten minutes. Its API docs let the mobile app integrate reminders without anyone explaining it in person. And a runbook tells the on-call engineer exactly how to restart the reminder service at 2 AM, step by step. None of it is long — but every piece saves real time, precisely because the team keeps it current.
- "Good code needs no documentation." Clean code shows how it works, but docs explain why it exists and how to use or operate it — things the code alone can't convey to a newcomer.
- "More documentation is always better." Focused and current beats exhaustive and stale. A huge, out-of-date manual is a liability; a short, accurate README is gold.
- "Docs are written once, at the end." They live and change with the code. Documentation written once and never touched again drifts out of date and starts actively misleading people.
- Documentation is how knowledge survives people leaving — without it, every departure takes irreplaceable understanding with it.
- README, API docs, and runbook are real, named artifacts you'll write and read constantly — knowing each one's job makes you immediately more useful.
- Understanding that stale docs are worse than none changes how you treat documentation: keep it current, or don't claim it's true.
Knowledge Check
What is the job of a README?
- To tell a newcomer what the project is, how to run it, and where to look
- To list out every single bug that has ever been found anywhere in the project
- To record the formal contractual promises that are made to customers
- To give step-by-step procedures for operating the live system
What are API docs for?
- Describing how to use the interface, so others can build on it
- Giving step-by-step instructions for restarting a broken live service
- Recording the major design decisions and the reasons behind them
- Giving a friendly overview to get a new developer started quickly
When is a runbook most valuable?
- When something breaks and an on-call engineer needs exact steps to follow
- When a brand-new developer is first trying to get the project to run
- When another team wants to call your software's interface from outside it
- When the team needs to record why a major decision was made
Why are stale docs described as "worse than none"?
- They actively mislead, sending people down wrong paths with false confidence
- Because stale documentation takes up far too much space on the servers
- Because writing any documentation at all just slows the whole entire team down
- Because out-of-date docs make the finished program run more slowly
You got correct