Write Decision Records, Not Documentation

The Constraint

Engineering teams need to preserve context for future decisions. The standard approach is to write comprehensive documentation that describes how systems work. This documentation requires ongoing maintenance to stay accurate as code evolves.

The Decision

Write decision records instead of traditional documentation. Capture why a choice was made, what alternatives were considered, and what tradeoffs were accepted. Let the code document how it works.

Decision records do not expire when the code changes. The reasoning remains valid even if the implementation is rewritten.

The Tradeoff

You lose the illusion of comprehensive, up-to-date documentation. New engineers cannot read a single document and understand the entire system. They must read code and decision records together.

You gain durable context. A decision record written three years ago explains why the database schema looks the way it does, even if the ORM has been replaced twice. When someone asks "why don't we just…" the answer is already written.

You also eliminate the maintenance burden of keeping docs in sync with code. Decision records are immutable. Once written, they require no updates unless the decision is reversed—which itself becomes a new decision record.

The Consequence

Code reviews improve because engineers reference past decisions instead of relitigating settled questions. Onboarding becomes faster because new hires read the decision history and understand not just what the system does, but why it does it that way.

Architecture discussions become more productive. When someone proposes a change, the first step is reading the original decision record. Half the time, the proposal addresses a tradeoff that was already considered and accepted for specific reasons.

The other half of the time, context has changed and the old decision no longer applies. The team writes a new decision record that supersedes the old one, and the architecture evolves with clear provenance.

Traditional documentation says "this is how it works." Decision records say "this is why it works this way." The first decays with every code change. The second endures because intent is more stable than implementation.

If you want institutional memory that survives team turnover and code rewrites, write decision records.