An Architecture Decision Record (ADR) captures one decision: what was decided, by
whom, when and why. ADRs are meant to be written once and kept. The interesting part
starts a year later, when some of them are no longer true.
January: PostgreSQL is the datastore. Primary keys are UUIDv4.
April: keys move to UUIDv7. The PostgreSQL decision, in the same record, still stands.
May: events go over LISTEN/NOTIFY. November: Kafka. The following March: NATS.
September: one identity decision replaces three earlier ones, spread across two records.
After a few cycles of this, anyone reading the decisions needs answers to a few
questions. A new engineer wants to know what's in force today. An auditor wants to
know what was in force on the day of the incident. A reviewer wants to know whether a
new proposal contradicts something already agreed. An AI coding agent given the folder
needs to know which of these statements to obey. A record that's been
replaced but isn't marked as such is worse than no record, because it is still
confidently telling people what to do.
To be fair to the tools: Word’s Track Changes,
Google Docs’ version history and Confluence’s page history are good at what they do,
which is recording edits to one document. Supersession isn’t an edit to a
document. It’s a fact about two or more documents, and those tools have nowhere to keep
it except inside one of the documents involved. A team can bolt something together
with page properties, macros and discipline, but it’s a local convention someone has
to maintain, not a standard.
These standards were designed in the late 1990s and 2000s for publishing,
legislation and aerospace documentation, where cross-referencing parts of many
documents and tracking amendments is the everyday job. They are ratified, stable,
and have several independent implementations, and they were designed to work together.