Records that help.
WHAT TO DOCUMENT
How to set the project up from nothing How to run it How to deploy it How to restore from backup
Architecture: what the parts are and how they connect
External dependencies and what they are for Significant decisions, and why
WHY THAT LAST ONE
Because the reasoning is lost otherwise, and the decision is then reversed by someone who does not know the constraint.
WHAT MAKES DOCUMENTATION FAIL
Being out of date.
WHY THAT IS WORSE THAN NONE
It is trusted.
WHAT PREVENTS IT
Updating as part of the change, not afterwards.
WHAT TO GENERATE RATHER THAN WRITE
API specifications, from the code.
WHAT TO KEEP SHORT
Everything.
WHY
Long documentation is not read, and not maintained.
WHAT TO TEST
The setup instructions, by following them.
WHO SHOULD TEST THEM
Someone new, who is the only person who can see what is unclear.
WHERE TO KEEP OPERATIONAL DOCUMENTATION
Somewhere reachable when the system is down.
