Architectural Decisions Revisited

Back in 2016 I wrote about Architectural Decision Records (ADRs) in my post "Why did we do it that way?". These are lightweight documents stored in a software project codebase along with the code that document point-in-time decisions about the architecture for future reference. Since then I have had projects that used them and others that didn't in lieu of other ways of documenting decisions.

I recently ran across a great post from Kelvin Meeks on ADRs that lists a lot of great information and resources. I also like the project he links to as an example containing a good number of records that is still an active project at the time I am writing this.

In fact, since my original post a Github Organization for ADRs has been created that includes articles, resources, guidance, and tooling for using these records.

If you have ever lamented not capturing why a choice was made or want to improve how decisions are documented by having them live right along with the project(s) they describe, see if ADRs might be a good fit for your situation.