ADRs were popularized by Michael Nygard’s blog post Documenting architecture decisions. Nygard does a great job explaining why they will be useful in the future.
They will give useful context about decisions for the people who weren’t around when the decisions were made, and also for people who were there but already forgot about it. This in turns allows being intentional about accepting or changing decisions.
However, they have benefits already today.
Writing things down clarifies your thoughts. I keep banging this drum, but it’s worth mentioning again. As you write an ADR, you will have to work through the details. This will clarify your thoughts and reveal the flaws in your arguments.
An ADR makes it clear if a decision was made. ADR is a kind of a design document, but not all processes for design documents track their status. This can become a problem because while you can find the old docs, you don’t know what was decided about them and whether they were ever implemented. This is bound to happen if nobody ever explicitly makes a decision about them.
ADRs can act as a forcing function. Nygard’s ADR template has a Status field. He suggests that the value can be “proposed”, “accepted”, “deprecated”, or “superseded”. The template also has a section called “Decision” that spells out the decision. This should make the situation clear. You would not mark an ADR as accepted unless a decision was made, right?
You still have to keep publishing new ADRs and mark the old ones as deprecated as you go along, but now you’ve got a process for it.
Blog meta
This is going to be the last weeknote of the year. I’m going to be off for a vacation. The next post is going to be my yearly yearnote for 2024. Happy holidays everyone!
Photo: A pile of firewood. ADRs are form a decision log, I suppose.