Introduction
Recently, I’ve been examining some of the roadblocks when it comes to the actual realisation of the benefits promised by Modern Cloud Platforms, DevOps, Platform Engineering, IaC, etc. In an attempt to isolate where common issues across large enterprises seem to exist. Maybe unsurprising to some, but one of the first examples of this I ran into was Architectural Practices.
The issue is not that architecture is a bad thing, more that in comparison to the improvements in tooling and processes that we have seen in the adoption of Cloud Native Technologies and modern software development practices, the same hasn’t occurred within the world of architecture. It seems this is to do with the fear or concern around the lack of governance and control, in a traditional architectural sense, when an environment moves at such a pace and in such an agile way.
In an effort to answer this problem, it seems a common solution to put stage gates of approvals, forums and review boards, however, these can be disproportionate to the decision, whilst also requiring large amounts of documentation, powerpoints and conversations to occur before endorsement.
So the question is; How can teams be empowered to make architecturally-significant decisions for their applications and platforms without conflict, a reduction in speed to market and delegated responsibility?
In my mind, part of the answer lies in the use of Architecture Decision Records.
What is an Architecture Decision Record (ADR)
The world first came to know of Architecture Decision Records (ADRs) in around 2007, where the term was coined by Michael Nygard in his book, Release It! Design and Deploy Production-Ready Software. However, it was his blog post in 2011, that it started to gain traction on a larger scale.
Architecture Decision Records are documented evidence of a justified design choice that addresses a functional or non-functional requirement that is architecturally significant. These significant decisions could be anything such as:
- Programming Language - Java vs. C#
- IDE - VSCode vs. IntelliJ IDEA
- Data Streaming - Custom Data Streams with Event Hub and Functions vs. Confluent Kafka
- IoT Networking - LoRaWAN vs. Wifi
Personally, I choose not to interpret the term “architecture” too seriously in this concept. Especially when starting a process enabling a business through the use of ADRs I would rather document all decisions that have a significant impact on the architecture or development of a system or platform documented.
The goal of ADRs and subsequent processes is to empower anyone to make a decision through the use of version-controlled, templated, and concise markdown documents. Which in turn reduces the amount of time to create, present and endorse a decision of significance, therefore, reducing the time taken to enable business outcomes.
Structure
There are some great resources available with templates and guides on how to structure your ADRs:
My standard approach takes a little from all of the above to help address concerns I have come across. Having a standard that is accepted within your organisation is the goal, if that means it slightly varies from what other organisations are using, but it works and is effective, then so be it. Below is the structure of what my ADRs look like, followed by a link to a GitHub Template of the structure.
Context
The context section should inform the reader of any of the:
- Background Information
- Circumstances
- Business Needs
- Requirements
Where they relate to the decision being required. Within the context section of the ADR, there should be a concise, three-sentence, description of the problem statement itself.
Options
I separate this section from context to highlight the various options that have been considered but also to ensure the context does not get influenced by the potential options.
The options section should have a dedicated subheading for the N number of entertained options. Each of which should have the below if suitable:
- Overview of the Option
- Summary of Pros and Cons relating to the option itself.
- Solution Overview Diagram
The options if possible should be listed in the order in which they were considered as the decision.
Decision
Typically the shortest section of every ADR. A sentence or two, typically stylised in a way to draw attention to the decision made.
Consequences
The consequences section describes the positive and negative consequences of the decision made. Specifically related to the context of post-decision. I.e. Are their secondary decisions now required, does this lead to something being retired or required to be altered? etc.
Additional Notes
This section is a space to put any links to reference materials, linked decisions, videos, or anything to support the content in the decision above.
ADR Example
The photos below are an example ADR used to decide which dog breed my Wife and I should choose. Whilst not a great example of a decision requiring an ADR, it is a fun example, additionally, I get to share a photo of Luna!
Note: We actually think she is a Staffy X Rhodesian Ridgeback.
Implementation Styles
Throughout this blog we have mentioned how ADRs should be version controlled and templated, with these two key points in mind it is really up to you how you implement ADRs within your business. Whilst there are a number of Open-Source tools that can be used to help implement ADRs, I don’t have any experience with those but I recommend checking out ADR-Tools, seemingly a long-time favourite. Below I’ve gone into a bit more detail about my two personal favourite methods.
Git Based
The use of a git-based platform, such as GitHub or GitLab, is very suited to versioning lightweight, text-based documents that can have numerous contributors. The major benefit of a git-based approach is that the ADRs are kept alongside the code ensuring that any decisions are alongside the resulting code accelerating the understanding of new developers or team members.
Additionally, this means that the developers or engineers writing the code can simply consume the template, instead of breaking their flow of work. In contrast to this is that it does break architects away from their traditional tools of choice and therefore may take an organisation longer to adopt this change.
The largest downside I’ve found to using a git-based solution is that the ADRs tend to become decentralised, and hard to report on, meaning some of the collective benefits of ADRs can be harder to achieve.
Confluence Based
Confluence is my personal favourite option for ADRs. It’s built for and supports the use of markdown-based editing, and is a collaborative approach to documentation storage and versioning. Especially when compared to something such as SharePoint.
For me, the strongest advantage that a platform such as confluence has is the ability to leverage the metadata features, through labelling to create reports and summaries of ADRs for reference. This enables a much more collaborative approach to ADRs and also opens the door to contributions from non-technical people.
Final Thoughts
We started this post by asking how teams could be empowered to make architecturally significant decisions, whilst that question has not been fully answered with this post. I’m hoping it has highlighted a path for a discussion on how ADRs can be a large part of an overall solution when it comes to empowering developers and engineers.
I may write another post in the future on the roles people play in the ADR process as well as a sample process for the management and endorsement of ADRs, let me know if this is something you are interested in.