Better Architecture Starts With Better Conversations

The summer before my senior year of high school, I worked as a paid intern at the Environmental Research Institute of Michigan (ERIM). My project used ocean elevation measurements from the TOPEX/Poseidon satellite. I wrote C++ and MATLAB software to extract data from CD-ROMs, organize it into coordinate grids, and generate 3D visualizations of ocean height.

At the end of the summer, I presented my findings to the institute’s president and other leaders. They asked good questions about the results and the tradeoffs I’d made.

I doubt anyone ever ran that software again. But if someone had opened the code months or years later, would they have understood why I’d made those choices? The reasoning existed in a conversation, not in a durable record alongside the code.

Years later, I encountered a larger version of the same problem at Control4.

When we were designing the OS 3.0 mobile applications, our senior engineers met regularly to evaluate UI architectures, including MVC, MVP, VIPER, and MVVM. We discussed the tradeoffs and the maturity of the available implementations. We also took meeting notes. Some of the reasoning was probably captured there, but those notes were eventually lost during a wiki migration.

The code survived. The context behind some of our decisions did not.

The problem isn’t just missing documentation

Engineers make decisions every day. Most are local to a function, class, or component and don’t need a formal process.

But some decisions affect other engineers, teams, or products. Those decisions need broader input and a way to preserve the reasoning. Without that, we risk revisiting the same arguments, repeating mistakes, or criticizing choices without understanding the constraints under which they were made.

The answer isn’t to have every technical decision made by a committee. Committees can introduce compromises that satisfy everyone on paper while producing a worse technical solution.

I wanted decisions to stay with the engineers closest to the work, while making sure the people affected by those decisions had a voice.

Let the team define the process

I’ve followed Martin Fowler’s writing for much of my career and put many of the patterns he discusses into practice. Andrew Harmel-Law’s Thoughtworks article, Scaling the Practice of Architecture, Conversationally, gave me a useful framework for scaling technical decisions through conversation rather than centralized approval. Architecture Decision Records (ADRs) were one of the tools it described.

ADRs weren’t new, but we hadn’t established them in my organization.

I had a practical reason for wanting to try them. Engineers would sometimes come to my office frustrated by decisions another engineer had made. Often, the disagreement wasn’t only about the outcome. They felt that their concerns hadn’t been heard or that their perspective hadn’t been considered.

We needed a better way to involve stakeholders without turning architecture into design by committee.

I also knew that engineers generally don’t appreciate having a new process imposed on them, especially one they’re expected to follow without helping shape it.

Around that time, I’d formed a small UI-Platform team in our Belgrade office: two engineers and a manager. The team was just getting started, had several architectural decisions ahead of it, and had the capacity to try something new.

I introduced the concept of ADRs, and we read through several articles together. Then I asked the team to create its first ADR:

An ADR defining how we would write and use ADRs.

It was a small decision with an important consequence. The engineers weren’t just adopting a process I’d designed. They were helping define it, testing it on real work, and improving it as they learned.

How we put ADRs into practice

We started with a standard template. It evolved over time, but the essentials stayed consistent:

• Context: What problem are we trying to solve, and why does it matter?
• Alternatives: What credible approaches have we considered, and what are their tradeoffs?
• Evidence: What did we learn from research, prototypes, or proofs of concept?
• Feedback: Who will be affected, what did they recommend, and how did we respond?
• Decision: What did we choose, why, and what consequences do we expect?

The ADR also included metadata such as its author, creation date, status, and stakeholders.

I encouraged engineers to consider multiple alternatives—often three where they were genuinely plausible—rather than start with a favorite solution and work backward to justify it. A proof of concept could be valuable when the tradeoffs weren’t clear.

But the document wasn’t the main point. The conversations it prompted were.

Seek advice, not unanimous approval

For the UI-Platform team’s initial ADRs, I identified Staff and Principal engineers and managers across my organization who should be consulted.

The author’s responsibility was to seek out feedback, understand the concerns, and take them seriously. Sometimes that meant revising the proposal or finding a compromise. Sometimes stakeholders disagreed with each other, and there wasn’t a solution that satisfied everyone.

We weren’t trying to design by committee. After making a reasonable effort to resolve concerns, the author was expected to make the decision within their authority and explain the reasoning, including why some advice wasn’t followed. Genuine blockers or decisions outside that authority still needed to be escalated.

That distinction matters: owning a decision doesn’t mean ignoring advice, and seeking advice doesn’t mean giving up ownership.

Keep the process visible—and the record close to the code

Our workflow used several states.

An ADR began as a Draft, while the author clarified the problem, explored alternatives, gathered feedback, and ran proofs of concept. Once the proposal was ready, it moved to Proposed and was shared with the affected teams. If no blocking concerns remained, it became Ratified.

We also tracked ADRs that were Rejected or Abandoned, recording why they didn’t move forward. Later decisions could Supersede earlier ones, with a reference to the replacement. The history mattered, including the paths we chose not to take.

During drafting and review, we used Confluence. Not every stakeholder had access to every team’s Git repository, and sometimes product managers needed to participate. The wiki made collaboration easier.

Once an ADR was ratified, we converted it to Markdown and committed it to an ADR directory in the repository closest to the code. We also preserved rejected and abandoned decisions. The important thing was that future engineers could find the reasoning where they encountered the implementation.

We established a review committee made up of the managers in my organization. But the committee didn’t review or approve the technical decisions. We reviewed the progress of ADRs, looking for proposals that had become stuck and needed help moving forward.

That was a deliberate separation of responsibilities. Engineering managers helped keep the process healthy; engineers retained ownership of the technical decisions.

Where judgment still matters

Not every decision deserves an ADR. Sometimes a conversation between two engineers is enough. The process should be reserved for decisions with meaningful impact beyond the immediate work.

It also helps to distinguish between one-way doors and two-way doors. Some choices are expensive to reverse once implemented. Others are easy to revisit. The amount of investigation and review should reflect the consequences of getting the decision wrong.

The process wasn’t perfect.

A small number of engineers became too attached to their proposals. They treated authorship as permission to dismiss feedback and move ahead with their preferred solution.

When I saw that happening, I worked with their managers to coach them through the process. Giving an engineer ownership of a decision doesn’t remove the need for judgment, collaboration, or accountability.

I also saw authors criticize previous architectural choices without fully understanding why those choices had been made.

One principle I’ve held for a long time is that we stand on the shoulders of giants. We often don’t know the constraints the engineers before us faced. A past decision may look wrong with today’s information but have been reasonable at the time.

An ADR won’t prevent every disagreement, but it can preserve enough context to let the next engineer evaluate a decision fairly—and improve on it when circumstances change.

What I learned

Over time, engineers appreciated having a consistent way to make and communicate decisions. It encouraged more discussion across the organization, made disagreements easier to surface, and preserved the reasoning that might otherwise have disappeared.

Having the UI-Platform team help define and trial the process made adoption easier. The managers’ review committee helped keep proposals from sitting indefinitely without taking decision-making authority away from the authors.

After two or three years of using ADRs in my organization, I introduced the approach to the broader organization through my VP’s Principal Engineering Committee. Rather than simply adopting our exact process, that group developed and tried its own. The result was similar, but the ownership was theirs.

That’s probably the most important part of the story.

The goal was never to produce more documents. It was to help engineers make better decisions, involve the people affected by those decisions, and preserve the reasoning for whoever inherited the code.

My responsibility as an engineering leader wasn’t to make every technical decision. It was to create the environment in which engineers could make good decisions themselves.

That’s a central part of my Engineering Operating System.