Deciding what is worth writing.
WHAT DOCUMENTATION IS FOR
Answering questions the code cannot answer.
WHAT THE CODE ANSWERS
What it does.
WHAT IT CANNOT ANSWER
Why it does it that way What was considered and rejected What constraints exist outside the code How to set it up and operate it How the parts fit together
WHAT TO DOCUMENT
Decisions and their reasoning Architecture and structure Setup and operation Interfaces others depend on Anything surprising
WHAT NOT TO DOCUMENT
What the code plainly states Anything that duplicates the code and will diverge
WHY THAT SECOND POINT MATTERS
Documentation that diverges is worse than none, because it is trusted.
WHAT TO PREFER
Documentation generated from the code, where possible Tests, which document behaviour and cannot diverge
WHAT TO KEEP MINIMAL
Everything, so it is maintained.
WHAT TO ASK
Who reads this, and what question does it answer?
WHAT TO DELETE
Documentation nobody reads, and documentation that is wrong.
