How an ADR saved the day!
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.
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:
Once *************
.Clientstarts supporting .NET Standard consumers, we can remove this workaround and fetch the license status from ******** directly.
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:
