Document Decisions or Repeat Them

# Document Decisions or Repeat Them

Here's what happens when decisions aren't documented:

Six months from now, someone faces a problem. They think about it. They explore options. They make a decision.

They don't know you already made that exact decision. You had reasons. You considered alternatives. You knew things about the context.

They make a different decision. Maybe better, maybe worse. Probably inconsistent with what already exists.

Now you have two approaches to the same problem in the same system. Future developers are confused. The codebase is incoherent.

All because the original decision wasn't written down.

Every undocumented decision imposes a tax: