by Leon Rosenshein

ADRs and You

I’ve talked about Architectural Decision Records before. Today is the 10th anniversary of Michael Nygard’s original article on them so I wanted to mention them again. Not just to remind folks that we need to record our decisions (which we do), but also as a segue to what, and more importantly, who an architect is.

According to Martin Fowler, “Architecture is about the important stuff. Whatever that is.”. While not terribly specific, it’s a pretty good heuristic. Add in the reality that while we might know the problem we’re trying to solve at the beginning, and maybe even have a good idea of the initial approach, we don’t know what we don’t know, so the final answer, and its architecture, can't be fully known up front.

Which brings us to the concept of doorways. Every choice we make takes us through a door. We become aware of new opportunities and we lose sight of the opportunities we had on the other side of the door. Some of those choices are easily reversible, even after some time has passed. Those are two-way doors. Others are one-way doors. Those choices are much harder to change after the fact. Those decisions need more deliberation and a lot more documentation of the why behind the decision. As noted above though, we often don’t have the information and context needed upfront to make that decision, and you can’t always know what kind of door it’s going to be until you get there, long after the “design doc” has been written.

Regardless, that decision, especially if you’re going through a one-way door, is an architectural decision. By definition, the person making an architectural decision is an architect. That means that at one or more times in the development cycle, we’re all architects. And those architectural decisions need to be recorded. Because at some point, after the decision has been made and implemented, someone is going to have a question about why the decision was made the way it was. Because a new use case or edge case or requirement has come up and needs to be addressed. That person is going to need as much context as possible to decide what can be extended, what needs to changed, and what needs to be completely redone.

And now we’ve come full circle. We’re all architects and architectural decisions need to be recorded. The way to do that is with Architectural Decision Records.