The ambiguity of architecture decision records

"I architect"

Imagine that there is a discussion during the daily standup where the team is trying to overcome a technical challenge.

"I decide"

Imagine that we are in a meeting, observing a discussion related to the architecture of a new part of the system.

Confused people remained confused, PowerPoint presentation kept all the decisions, completely ignoring the facts that happened since 2 years passed, when this presentation was made.

"I record"

Next time, there was another meeting named "Dev team & arch sync", where the same people gathered. There was no agenda, 25 min planned.

Where is the value?

Have you experienced something similar, dear Reader?

Decisions in PowerPoint slides, outdated and forgotten Word documents that are never read.

Produced by individuals, not even architects, but in total isolation from "the doers".

"Architecture Decision Records are not needed, as no one reads them" - one might say.

"Only architects should decide, as they have the big picture" - another one could argue.

Well, both observations, and many others, might be actually "true".

It varies from company to company, team to team, and even person to person.

It's a slippery slope to say "we do ADRs here" and not fall into Tools make fools type of a problem.

But as with other tools (and I believe ADRs are "just" a tool), the value is in the reason we use them.

Often, people are not aligned on why they do certain things.

A solution is picked and all just do what is needed to satisfy going in this direction.

What about other options?

What is the current context?

Every best practice, when misapplied, becomes an anti-pattern.

Are there any design constraints?

Any Decision Records?

Turns out that we often "feel" what might be a good approach for a given problem.

Considering that we are dealing with an actual problem, not the one that got "solutioned" (or in other words, "coming up with a problem to bravely solve it").

It might be that the real value of "Architecture Decision Records" is not in recording decisions, but in thinking about them.

Going through the processes of collaborative designing, sketching, and figuring out the surroundings.

It's very easy (as a reminder - Simple isn't easy!) to look at ADRs as a static "thing", just being there.

Magic starts when we think of it as a process.

A stream of events that is produced when people meet together and become the Overmind - all to collectively bring multitude of perspectives, experiences and knowledge.

During such sessions, all learn - sometimes it's about approaching architectural problems, dealing with trade-offs, and in other times - just learning that patience is really vital when working together.

A nice side effect is that we get a record that more-a-less captures the context, rejected options and the solution candidate.

Recently, LLMs can help with mundane tasks like formatting, etc.

What's more, when decisions are recorded, LLMs could help with building the knowledge stream of decisions.

Of course, it's a different problem how to make it useful, but we have tools at our disposal.

Design Deciding Process?

Similar to a Zen Koan, we could express:

Play a role in the stream, participate in the process, experience Panta rhei!

Slow down and become one with the Overmind.

Laying down the options, seeing the current context - this really contributes to better understanding.

And seeing those trade-offs.

A true power of a senior engineer or an architect is the ability to "produce" more senior engineers and architects, not solving hard problems or drawing eye-catching sketches.

No single ninja, rockstar developer or hero architect will provide a long-term value.