Write Decisions for Whoever Inherits the Code

The most valuable documentation I write is also the shortest: a few lines recording a decision and the reason behind it.

Code is good at showing what a system does. It is almost useless at showing what you decided not to do. The obvious library you rejected, the simpler approach that fails a constraint you cannot see in the source, the reason two things that look mergeable are kept apart on purpose: none of that survives in the code. It lives only in the head of whoever made the call, and that person eventually moves on.

So the strange choice you left behind reads, to the next person, like a mistake. They see the non-obvious approach, assume nobody thought it through, and "fix" it straight back into the problem you were avoiding. Now the bug is back, and the fix that caused it looks like an improvement in the history.

A decision record is a message to that person. It does not need to be heavy. What was decided, what it was chosen against, and the constraint that made the difference. Three lines is often enough. The value is not in the writing, it is in the fact that the context exists somewhere findable at the moment someone is about to undo it.

The hard part is that the context worth recording always feels too obvious to write down today. It is not obvious. It is just fresh. In three months it will be gone, and the only version left will be the one you wrote for the person who inherits the code.