In 30 seconds
- Working software shows real progress; documents only describe intent.
- Write the documentation that helps people build, use and run the product.
- Skip documents written only to prove work was done.
What it means
A demo of a thin working slice tells you far more than a long specification. This value, the second of four agile values, puts working software first as the main measure of progress.
Documentation that still matters
- API and integration docs others rely on
- Architecture decisions and their reasons
- User help for anything non-obvious
- Operations runbooks
- Records required by regulation
Finding the balance
Ask who will read a document and what they'll do with it. If no one, skip it. If someone, keep it short and close to the code, and update it as part of the Definition of Done.
Myth vs reality
Myth · Agile teams don't document.
Reality · They document deliberately, not by default.
Myth · Code is the only documentation needed.
Reality · Code shows how, rarely why; decisions still need writing down.
Myth · Specs are banned.
Reality · Light specs and examples are fine when they help.
FAQ
What about regulated industries?
Produce the required records, ideally generated from the work itself.
When should docs be written?
As close as possible to when the work is done, not long before or after.
Who decides what to document?
The team, with input from whoever will rely on it.