The summary.
DOCUMENT WHAT THE CODE CANNOT ANSWER
Why it was done that way, what was rejected, what constraints exist outside the code, and how to operate it.
Documentation duplicating the code diverges, and divergent documentation is worse than none because it is trusted.
ONCE SOME DOCUMENTATION IS KNOWN TO BE WRONG, NONE IS TRUSTED
Fix it or delete it immediately. Nothing is better than something misleading.
THE README DETERMINES WHETHER ANYONE CAN USE THE PROJECT AT ALL
Test its setup instructions on a clean machine — that reveals every step nobody wrote down.
DOCUMENT THE ERRORS AN INTERFACE CAN PRODUCE
Callers must handle them, and undocumented errors are handled badly or not at all. And examples are what people actually use.
WRITE RUNBOOKS FOR SOMEONE UNDER PRESSURE, AT NIGHT, WHO DID NOT BUILD THE SYSTEM
Exact commands, no assumed knowledge, and what to do if a step fails.
Keep them reachable when the system is unavailable — documentation stored inside the failing system is useless during an outage.
