Architecture Decision Records (ADRs)

December 18, 2018 #architecture #agile

Recently, I was asked to do an architecture review on a couple of projects - one was just getting started, and the other was a PoC demoed at a user conference.  Unfortunately, as with too many “agile” projects, existing architecture documentation could fit on a post-it note.

This situation was explainable, but something I wanted to change going forward.  Given these were cloud-native projects looking at newer PaaS services, I concede that it is hard to know the entire architecture up front.  However, creating a simple Lucidchart diagram with ~10 icons doesn’t take long, so I took my best guess and made one for them.  I am OK with emergent design distributed amongst the team, but there needs to be a way for architecture documentation to happen.

I remembered something from a ThoughtWorks blip called Lightweight Architecture Decision Records and did some google searching.  Distribute Design Authority with Architecture Decision Records | Agile Alliance is a good article on the topic with a good set of references (for which I added links):

Anyone using Architecture Decision Records?  If so, are you storing them on a wiki, or alongside your source code?  What about diagrams - Lucidchart (easy to access/collaborate) or something like where you can check in the .xml into your repository?

© 2020 Kevin Hakanson (built with Gatsby)