As a system evolves, so does its architecture.
The challenges for software teams are to make sure that changes are made in a coordinated and consistent manner to ensure the system stability and evolutivity.
Software systems are complex entities composed of multiple subsystems that in turn are composed of multiple components that can be impacted by changes.
Organizations have to solve that problem with a balance between central and local design authority and decision-making to support an efficient collaboration.
InfoQ ranked Architecture Decision Records (ADRs) as an “early adopters” practice being adopted in the ecosystem; Amazon just released a guide for example.
This article shares how Architecture Decision Records can help software teams build and deliver better and faster software.
Clearly formulate the problem to solve
Architecture decisions are needed because a problem must be solved and involve changes to the system.
Understanding the problem is therefore a prerequisite of implementing changes.
“A Problem Well Stated is Half Solved”—Charles Kettering
An ADR starts by defining the “context”—an opportunity to clearly state the problem to be solved and align stakeholders on the same page.
Defining a problem requires to:
- Assess possible causes
- Understand their origins
- Prioritize remediation actions.
All these activities allow efficient problem-solving manner that maximizes the value delivered in a defined timeframe.
The identification of multiple causes also enable to address different issues with different priorities and timings, improving implementation quality and speed.
Lastly, a clear problem formulation helps to step back on the big picture, assessing the real need to address this problem first, and how it contributes to the big picture.
Take decisions in-line with the target
Project and product teams have the imperative to deliver within resource constraints of time and budget, usually leading to picking the “easiest and fastest option”.
While limitations are healthy, they can lead to too many short-term actions that reduce quality and speed, especially when no counter-forces are in place.
The target architecture is the north star of the business and all teams without the short-term time constraints of projects, acting as a real counterforce for decision-making.
Applying that force, Architecture Decision Records identify multiple scenarios able to solve the defined problem but also consider the progress towards the target.
That difference of perspective can lead to small or large changes in decisions, avoiding reworks done later with a much higher cost.
Decisions more in-line with the target does not mean that a central architecture team makes all decisions—what is important is to move forward as a team.
Explicit decisions to move forward
People need to feel involved and part of the decisions that affect them to move forward with confidence and trust.
The problem is that involving too many people for decisions consumes time and resources organizations do not have.
Architecture Decision Records (ADRs) are an effective way to balance the implication and information of multiple stakeholders.
Stakeholders can be involved depending on their profiles:
- At the beginning and decision-making for busy executives
- From definition to recommendation for impacted persons
- Maintain informed asynchronously for less impacted stakeholders.
The effective balance of involvement contributes to sharing the knowledge in the organization aligning better the why of decisions, and future iterations.
The collaboration of different profiles is also an opportunity to increase quality by:
- Identify multiple requirements (e.g. security, usability)
- Generate and assess better the possible options
- Align the scope of changes across the entire system.
Using ADR is a form of Shift-left improving the “by-design” identification of the scope, functional and non-functional requirements limiting reworks afterward.
The process also leads to creating organizational habits that contribute to operational excellence.
Set foundations for operational excellence
Better and faster software requires to grow the overall software engineering maturity that can only be done on solid foundations.
ADRs contribute to operational excellence as decisions are:
- Centralized in one place
- Systematically recorded
- Standardized with pattern
- Clearly stating problem
- Streamlining decision-making.
These characteristics set the stage to foster the collaboration on the shared place, avoiding inefficient questioning and sharing through email, chats and other.
By being open, searchable, and written in plain language, ADRs are understandable by many stakeholders across the organizations, without them being expert of each knowledge.
Lastly, the systematic recording of decisions enables one to keep a clear changelog of the evolution happening over months, an information usually lost.
And as information is centralized, other processes can be built upon like the update of cartography, follow-up items, technical debt backlog, or documentation update.
In the end, ADRs lead to support more change and the growth of the organization.
Support the organization scalability
Organizations succeeding in the digital transformation are able to rapidly adapt and grow their entire software system, from people to technology components.
The challenge being to equilibrate quality and speed of architecture decisions, teams need a way to ensure that many local decisions do not impact the overall consistency.
ADRs support the scalability of organizations favoring an asynchronous collaboration on the architecture decision process.
Scalable organizations are able to balance:
- Authority between central and decentralized decisions
- Effort dedicated to analysis and decision-making process
- Involvement of internal and external stakeholders.
Organizations usually start with a central design authority, allowing them to adopt the process through practice, before decentralizing gradually.
With maturity, teams usually start to differentiate “light” ADRs for smaller decisions requiring less formalization and stakeholders involvement.
One effective way to evaluate the ADRs effort is the concept of “1-door” or “2-doors” decisions from Jeff Bezos, differentiating structuring versus reversible decisions.
It’s all about improving towards Quality at Speed software.
ADR for better and faster software
Architecture Decision Records are an effective practice for organizations searching to scale their engineering practices.
The methodology is aligned with the Quality Engineering paradigm for progressive and incremental value delivery.
The process can be started in a light mode with a few people before deploying across the organization for better and faster decisions.
Implementation guides are available below in the references of this article, letting you decide “the right thing” before delivering “the things right”.
What’s your next ADR?
Thomas Betts, Eran Stiller, Software Architecture and Design InfoQ Trends Report—April 2022. InfoQ.
Architecture decision records overview, Google Cloud Architecture Center.
ADR process, AWS Prescriptive Guidance.
Architectural Decision Records, GitHub.
Joel Parker Henderson, Architecture decision record (ADR), GitHub.