How an ADR saved the day!

Sami Lamti
Dec 4, 2020 · 2 min read

One of the engineering principles we adhere to at Redgate, is to write down Architectural Decision Records “each time anyone is about to embark on a significant architectural change”. The steps we go through are:

  • Do planning before building something new. This can be in-person white-boarding or just talking it through with the team members, if you’re all clear on how you will get things done. We encourage looking at existing ADRs and using a similar approach.
  • Capture this plan in a short, written document. Once it is clear to the team how and what you do, it should be relatively quick to write down the “how”. Don’t go overboard. Review this plan with your team.
  • Submit a PR to this repository and merge it. Other teams can look at your ADRs.
Filing cabinet by Maksym Kaharlytskyi on Unsplash

Recently, having such a record, came in super handy, as we were trying to resolve a licensing issue wherein our library was called from a .NET Core application through a .NET Framework, using a custom communication protocol. It was all very … convoluted and — more importantly — didn’t do what it was supposed to.

The fact that no-one from the original team was still with us, didn’t make things easier! After tearing our hairs out for quite a while, one of the team members offhandedly asked “shouldn’t there be an ADR for this?”, prompting us to look into the shared repository. There was! And right in it, it said:

Much easier! Now we could remove a lot of very intricate code (which admittedly made sense and had value at the time it was written), get to the root of the actual issue and resolve it quickly.

Consider writing ADRs and share them within your organization so that future teams can get an on-demand insight in how and why previous decisions were made!

If you’d like to know more about ADRs, I’ve collected some additional resources for you:

Ingeniously Simple

How Redgate build ingeniously simple products, from…

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store