Why every Engineering Manager should maintain an Architecture Decision Record

Are you one of those managers who are often asked questions on -

• why are we using this technology and not that? or
• why do we use this design pattern and not that? or
• simply why are we doing certain things in this particular way only?

Sometimes when new members join your team, they will have many questions around design, techniques, patterns and technology choices. You as an EM need to provide clarity to everyone on your team so that you not only establish transparency and openness but also enable team members to make informed decisions. And with each new member joining the frequency of these questions only increase. So what do you do? Repeat? No.

Say hello to Architecture Decision Records [ADRs]

What is an Architecture Decision Record [ADR]?

In the world of software, Architecture Decision Record is a technique to capture important architectural decisions along with their context and consequences

There is no doubt that architecture is crucial in shaping the solution. As the solution evolves over a period of time, numerous decisions are being made. Some of those decisions may either become irrelevant or outdated in the light of new information. Its important to keep track of such decisions across the time axis.

The Thoughtworks Tech Radar mentioned ADR in the ADOPT zone in May 2018.

Lightweight Architecture Decision Records | Technology Radar | ThoughtWorks

Why do we need an ADR?

ADR is a log of significant architecture decisions captured in a given context. As mentioned in this article’s introduction, it comes to your rescue when new members join a team. Sometimes its helpful when your stakeholders wish to understand the impact of architectural changes to an existing solution. Having an ADR ready helps all to understand the history of decisions and bounds of the solution in question.

Lets look at some examples where you can have ADR -

1. Which framework will we use for writing the UI automation tests?(Protractor/Cypress/WebDriver)
2. Where will we store data? (cloud/local and files/databases)
3. Which type of database will we use? (SQL/NoSQL. If NoSQL, which type)
4. Which caching strategy will we use? (Write-through cache/Write-back cache/Read-through cache)
5. Which persistence mechanism will we use?
6. What will be our logging strategy? (what to log/which framework to use/formatting (JSON or KVP))

If you notice the examples above, these questions are written in future tense. Its more for the future engineers or stakeholders. Hence it goes without mentioning that we should find answers to these questions BEFORE we adopt anything in the project.

How is an ADR captured?

There are multiple templates available to capture ADRs. It is advisable to capture the following things in an ADR-

ADR Skeleton

Some Tips to write an ADR

• You may use a lightweight markdown language to prepare an ADR
• ADRs are to be numbered sequentially and numbers cannot be reused
• If a decision is reversed, keep the old one around, but mark it as “superseded” with a reference to its replacement because its important to have a record of old decision
• Decision is stated in full sentences, with active voice. Like “We will …”
• All the Consequences should be mentioned, not just the positive ones
• Lastly, the ADR may be 1 or 2 pages long max :-)

Final Thoughts

The most important thing to document in these design records is not just what you decided to do; it’s also what you considered and decided not to do.

References:

1. https://www.thoughtworks.com/radar/techniques/lightweight-architecture-decision-records
2. https://codeahoy.com/2017/08/11/caching-strategies-and-how-to-choose-the-right-one/
3. https://logz.io/blog/logging-best-practices/
4. http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions

If you liked my article, consider giving multiple thumbs-up.