Welcome back to our series on facilitating software architecture and design, where we dive into the real-world challenges of changing systems. In this episode we discuss a core principle for effective system change: transparency.
Last time, we introduced the core problem we’re trying to solve: shifting from a bottleneck, “ivory tower” or “hands-on” architect role to a more facilitating role where teams are empowered to make their own architectural decisions.
From Bottleneck to Facilitator
A common misconception is that only the “ivory tower” architect, who is far removed from the code, can block progress. But a hands-on architect can also create a bottleneck. In both scenarios, you are relying on a small group of people to make all the decisions. This can lead to delays and, more importantly, decisions made without sufficient context from the people actually building the software.
To make this shift, we need to empower the teams doing the work. The people writing the software are the ones with the real information. Our role as architects should be to facilitate their decision-making process. This is where transparency becomes critical.
The Power of Transparency
Transparency in decision making is a powerful tool to begin improving decision-making, no matter where your organization is on its journey. The process of making a decision—from agreeing on the problem to exploring options and finally choosing a solution—can be lengthy. Transparency means documenting this process.
Have you ever joined a new project and wondered, “Why did they make this decision?” Every team member has. You often have to become a historian, digging through old chats or asking people who were there. The problem is, these stories are often incomplete.
Writing things down helps create an accessible record of what happened and, most importantly the context of that decision.
Starting with Decision Records
A great way to introduce transparency is by using Architectural Decision Records (ADRs). While ADRs have been around for a while, they are often misunderstood.
Some issues are about adoption. For example, if writing them after a decision has been made, it can become a tedious task similar to writing a unit test after the code is already working. This will only capture the information that someone still knows after the decision has been made. It will most likely not include the information captured during the process of making the decisions, potentially losing valuable insights and knowledge to readers later on. Additionally, it does not explain how a group of people arrived at their conclusion.
Instead, we recommend using ADRs as a living document throughout the decision-making process. Start a new ADR as soon as a problem is identified, and add to it as you explore options, list pros and cons, and gather opinions from different team members.
This collaborative, in-the-moment approach to ADRs helps in several ways:
- It makes conversations transparent. Instead of hallway gossip and conflicting stories, you have a shared document that reflects what everyone has agreed on.
- It forces explicit thinking. When you write something down, you clarify your own thoughts. It turns vague ideas into concrete statements.
- It prevents repetitive meetings. When a decision is well-documented, review meetings become more focused. Instead of re-hashing the same points, you can quickly get on the same page and move forward.
Just Start
Implementing ADRs doesn't have to be a top-down, bureaucratic process. Start small. Find one other person on your team and start writing them together, out in the open. As people see the positive impact—clearer communication, fewer repeated conversations, and better decisions—they will naturally start to adopt the practice.
This approach transforms the ADR from a burdensome task into a useful tool for thinking and collaboration. It’s an experiment you can safely start on a small scale, and the benefits can be huge.
What's Next?
In our next episode, we’ll dive deeper into the process of decision-making itself. We'll explore questions like:
- Who should be making the decisions?
- What does a good review process look like?
- How can we use writing as a tool for thinking?
Stay tuned! We would love to hear about your experiences. Feel free to join the conversation on Discord and tell us how you've used transparency and ADRs in your own teams.
