The maintenance problem.
WHY DOCUMENTATION DECAYS
It is separate from the code, and nothing forces it to change.
WHAT DECAYED DOCUMENTATION CAUSES
Wasted time Wrong actions taken confidently Loss of trust in all documentation
WHY THAT LAST POINT MATTERS MOST
Once some is known to be wrong, none is trusted.
WHAT REDUCES DECAY
Keeping documentation with the code, in version control Updating it as part of the change, not afterwards Reviewing it in code review Generating what can be generated Writing less
WHY WRITING LESS HELPS
Less to maintain means more of it stays accurate.
WHAT TO REVIEW PERIODICALLY
Setup instructions, by following them Runbooks, by using them Architecture diagrams, against reality
WHAT TO DO WITH DOCUMENTATION THAT IS WRONG
Fix it or delete it, immediately.
WHY DELETION IS ACCEPTABLE
Nothing is better than something misleading.
WHAT TO RECORD
When each document was last verified.
WHAT TO ASSIGN
An owner for anything important.
