As technology architects, we are expected to make decisions. Architectural decisions. Often, these are large scale, important, complex, impactful decisions that have long term implications and cross organizational reach.
Yet, decision after decision, we so frequently question our choices and the choices of others. Something just feels wrong. It feels off. There's an uneasy feeling that we missed something. That we didn't take this or that factor into account.Â
Why did we choose to use event streaming for that Customer Order system? Did it really make sense? Why did we choose that particular COTS (Commercial Off The Shelf) application? Is that vendor really delivering what we expect them to?
No one can tell for sure. There is no audit trail. No record of the decision being made. No one can recall the process or the discussions related to making these decisions.
I remember one such project where I had joined as an architect. It was a very large institution with hundreds of architects of all kinds - solutions, software, and enterprise architects among other "architect" types of roles. I was about to assume ownership of an application that was at its infancy but where the foundations had been laid out by another architect who had left.
There was some rudimentary documentation that was left but nothing too detailed. Yet, there were some major decisions already premade for me. There was a SaaS product involved. A product that had a price tag of several million dollars per year. There was a cloud environment used in a number of ways but not in other ways. There were databases and data lakes and integration points with other systems that seemed odd and out of place.
This is what I had to work with in building the rest of the product and finalizing its architecture and design.Â
There were a lot of decisions for me to make based on what has already been decided for me. But, there was no clear framework or guidance on how to do that. If that wasn't enough, I had to justify the decisions that I made as well as the decisions that were made before me. All of these I had to present and defend in front of the Architecture Review Board.
Going about this decision-making process was exhausting to say the least. From conversations I had with other architects, I realized that I was not the only one feeling that way.
I wanted to understand why.
Why was it that in an organization that seemed to have such an enormous architectural and technological presence - the process of architectural decision making was so draining?
My realization was that it was because the process of architectural decision making simply did not exist.
Despite the architecture review boards, and enterprise architecture involvement, and stout budgets - there was no process for IT architects to use when embarking on the journey of making an architectural decision.
My second realization was that even though I couldn't even begin to establish that kind of process for the entire company by myself, perhaps I could at the very least do something for my project and my immediate team. It may not end up being perfect, but it could be valuable.
Then I began to think. What exactly was it that was missing? In other words, what would the right architectural decision making process entail?
Documentation
Well first off. There was no documentation. Nothing was recorded. Technical decisions and the rationale behind them were not documented. Not even the large scale decisions that cost the company millions of dollars each year.
So I thought that would be a good place to start. I began documenting the actual decision making. At first, it was as simple as putting down relevant information as a free form text in our Confluence.
Then, it became more structured. Eventually, I began using a simple, yet effective format to track the process around this type of technical decision making.
I call this structure the Technical/Architectural Decision Matrix. Its goal is to highlight the different aspects of each technical option. It doesn't necessarily need to convey all of the detailed technical information that went into investigating each option. That can be left to other types of documentation. What it does though, is centrally collect all of the most important aspects of each option so that the decision making that goes into each option is made transparent and obvious.
This is the structure of that matrix. For each option, you will list the following:
Option Name: A simple identifier for the option.
Description: A clear but short description of what the option entails.
Pros: The benefits of the option.
Cons: The downsides of the option.
Risks: The risks of implementing this option.
Implications: The overall implications (positive or negative) of implementing the option
You can also add things like Costs or Risk of Not Implementing the option.
What documenting technical decisions in this way does, first and foremost, is that it helps you structure and frame all of the pertinent information. This in turn helps you make an informed, and therefore correct, decision.Â
Without this documentation, the decision making process is haphazard and opaque. It's hard to track and reason about why certain decisions are made and how. It's easy to forget and miss important information.
Some might say that this will only help others understand the decision making process better but not necessarily the person going about that process at the time. But that's not true. Even as the decision maker, this helps you organize things better in your mind and helps reason about each option in an objective, clear, and informed way. It also helps the decision maker to communicate the options to others and to get informed feedback from them.
This has helped me tremendously in that role - once I started documenting the technical options. It helped my own architectural thinking as well as the socialization and negotiation of the different options to stakeholders.
But, documenting the various options alone isn't enough. It's a wonderful and important start. However, there's more to it than that.
Architectural Decision Records
Recording options in the matrix described above helps you with narrowing down and rationalizing through which option you should go with in a clear and transparent manner. However, this happens before the decision is made. Simply put, this is the process by which you will be making a particular decision.
Once that decision is made, the result also has to be documented as such.
This is where Architecture Decision Records or ADR come into play. I wrote about ADRs and their importance in another article - Losing Track of Technical Decisions? Use Architecture Decision Records
In short, these architectural decision records are key to keeping track of your decisions and create an audit trail for decisions throughout time.
Going back to my personal example earlier in this writeup - how often have you had to look at somebody else's decision and couldn't begin to understand why that decision was made? Pretty often, I would dare to assume. It happens all the time. The reason is because no one bothers to record technical or architectural decisions once they are made.
Using a simple format as I describe in the ADR article above. goes a long way to creating visibility and transparency around these technical decisions. Whether in Confluence, Notion, or your code repository in Markdown, recording these decisions takes out the guesswork from trying to understand why we went one way and not the other.
It also minimizes the risk of an important decision being overwritten after a while due to the original rationale for it being forgotten.
So ADR is another simple yet powerful tool to streamline and help the architectural decision making process.
Now, this is all fine you might say. But, how do you actually make these a part of the process for your team or organization? A large corporation at that?Â
How do you implement these improvements so that they are part of the actual decision making flow within your organization? And how do you do that as someone who is not necessarily in a position to reform organizational processes on a large scale?
Here's an approach that I used multiple times as a software developer, technical lead, and architect - before I went into roles where I could directly decide and influence how these things are done.
The key here is in establishing a clear, transparent, streamlined, and strong architectural and technical decision making process and gradually convincing stakeholders of its value. Easier said than done, of course. However, it is doable if we apply some creativity, persistence, and out of the box thinking.Â
Whenever we think of architectural options, we go through a process of evaluation. The problem is that, in many organizations, that evaluation is implicit. It is not done in a mindful and deliberate way. It is not documented, and therefore is not repeatable. Nor is it transparent.
The way to implement a better decision making process within a large organization is to start small and get incremental buy-in from your stakeholders and/or team.
Step 1: Set an Example
Software architects and developers often think that it isn't in their power to change things that go beyond their scope of responsibility, ownership, or authority. There is some truth to that of course, but you wield a lot more influence and power than you give yourself credit for.Â
The key is that you cannot simply command an organization to apply the changes you are suggesting. You need to convince the organization.Â
You start doing so by setting a concrete example that you can later use to demonstrate the value of what you are doing.
First, identify an architectural problem where you or someone else had to make a decision among several options. It could be something that happened in the past. Or - something that is being worked on right now.
Use the aforementioned Technical Decision Matrix to document the options being considered. Doesn't have to be anything complicated. Simply something that conveys the main highlights of the decisioning that was or is being done.
Then, document a simple ADR if a decision has already been made in the past based on these options.
Step 2: Get Limited Buy-In
Once you have documented some options and have something concrete on your hands, it's time to start bringing this to the attention of others.
Find a few team members or stakeholders who you know are affected by the lack of concrete architectural decision making process just like you are. These can be other architects, developers, managers, product owners, etc.
Show what you have documented to them and explain how much this type of documentation will help in streamlining the process and in helping alleviate the current challenges - at least to some degree.
It helps to create some kind of a presentation where you list the pros of such a process and the risk of not implementing it.
That latter part is crucial because it demonstrates the pitfalls of not going with what you are suggesting.
Once you get buy-in from a few stakeholders and you have garnered some concrete support you can move to step 3.
Step 3: Socialize to a Wider Group and Get Buy-In
Here, you will communicate the exercise that you went through and the benefits of it to your team or a group of stakeholders. This may be through a presentation or a workshop or a series of presentations you hold on the topic.
Ask the stakeholders the support of whom you have garnered in step 2 to help make your case.
The goal is to convince the group that the exercise you have gone through is valuable and get the team on-board with implementing your process of architectural decision making into their day to day work.
To help facilitate the change in behaviour and to make it easier for the team, you can suggest to do a "trial run" where the team can implement the process for a period and then reassess and validate whether the process helps or only makes things harder.
The key here is to implement these changes in small increments and not to demand sweeping modifications to the way that the team works. Doing the latter is likely to increase resistance and pushback against the new process.
What team members can start with is as simple as:
Documenting a rudimentary decisioning matrix next time that someone needs to make an architectural decision regarding a solution, system, application, or anything else with significant enough technical or architectural impact.
Use the matrix in socializing and discussing the solution and the various options with the rest of the team.
Document the resulting decision as an architecture decision record (ADR)
To ease the process for the team, you can even volunteer to facilitate the architectural discussion that will stem from the decision matrix. This can take place during an Architecture Review Board if such a forum exists in your organization or it can be a different session.
You will also need to assure the team that you will be there to guide and support as they go through the process. This is something that will be key in enhancing the success of the new process being established as part of the team's operating model.
Summary
There is an important need within many organizations to streamline their technology and architectural decision making. Oftentimes, there is no process for this kind of decision making at all. The lack of this process or it being ineffective leads to confusion, missed information, and increased risk.
Moreover, it creates decision making fatigue among software engineers, architects, and other technical and non technical stakeholders who have to make these decisions or who are reliant on them.
Without a clear, effective, and repeatable framework, decision making becomes draining and inefficient. Instead of driving progress, technology decision makers find themselves caught in repetitive debates, uncertainty, and increasing operational risk.
Organizations that fail to address this pay the price in lost time, unnecessary complexity, and reduced agility - not to mention the high likelihood of missing important architectural considerations that can lead to severe organizational problems down the road. The need for a streamlined, transparent decision-making process is therefore critical for the success of the organization.
There are several keys to this process:
Making the technology decisioning effort visible and structured via documenting an Architectural Decision Matrix that focuses on key aspects of each option.
Using the matrix to fuel architectural discussions through an Architecture Review Board or another similar forum.
Recording the decision as an architecture decision record after the decision is made.
This article offers one simple and palatable way to implement such a process without mandating sweeping changes for the organization. It involves creating such a matrix for one particular area that required architectural decision making. Then, socializing that matrix to the team. Eventually - suggesting to implement the process using a "trial run" with minimal effort required.
This approach has the benefits of:
✅ Reducing resistance - small changes are easier to accept
✅ Showing quick wins - keeps momentum going
✅ Building credibility - people start trusting the process
If you are seeking to become an IT/software architect, or want to get to the next level as someone who is already in this role, you may want to check out a guide I wrote about just that. It's called Unlocking the Career of Software Architect, and I had created it with the aim for it to be a comprehensive resource for those who want to thrive and succeed in technology architect types of roles.
