How to Make #Architecture Decisions: #RFCs, #ADRs, and Getting Everyone Aligned
Excited for #JCON EUROPE 2026? See Piet van Dongen at #JCON2026 in Cologne talking about 'Creating Effective and Objective Architectural Decision Records #ADRs'
#Documenting decisions is like eating your veggies as a kid: they …
🎟️ 2026.europe.jcon.one/tickets
Free for #JUG members
New article is live on my WriteFreely:
“Technical debt isn’t just code, it’s lost context.”
Most teams can point at code debt: missing tests, messy modules, shortcuts taken under pressure. The harder (and often more expensive) debt is the part you cannot point to: the *why* that evaporated. The moment a reasonable decision becomes an undocumented assumption, then a “hard requirement,” and finally a constraint that nobody dares to touch.
The article is built around a pattern I keep seeing in real systems: **Decision → Assumption → Constraint → Incident (or slow bleed)**, plus the symptoms that show up in delivery, operations, and team dynamics when context turns into folklore.
I also propose a few lightweight countermeasures that do not require a documentation bureaucracy: mini-ADRs that take ten minutes, PR prompts that force future-facing context into the open, a simple “folklore detection” checklist, and a realistic 30-day adoption plan for normal teams.
If you’ve ever inherited a system where “don’t touch that, it caused an incident last time” was considered documentation, this one is for you.
👉 https://authorial.org/byern/technical-debt-isnt-just-code-its-lost-context
#SoftwareEngineering #TechnicalDebt #Maintainability #EngineeringCulture #SoftwareArchitecture #Documentation #ADRs #KnowledgeManagement #ByernNotes
The real consequential decisions in engineering aren't made in sprint planning. They're hidden in the 'invisible choices': metrics, defaults & everyday behaviors.
The industry is focused on the wrong things. The choices that truly shape systems & culture are the ones that go unnoticed and unexamined.
Read the full insights: https://bit.ly/43Ajl1y
Understanding a software system by reading ADRs is a bit like event-sourcing its architecture in your head. You get the whole history (enabling deeper understanding), but if you just want to get information about the present state, it's not very efficient. Hence, keeping a snapshot of the current state (a read model if you will) in some form is still worthwhile.
@RuthMalan It's the "and then" part that's the problem. I write the ADR before making the decision, using it to drive discussion and evaluate options (and record the options, too). That's where most of the value comes from for me.
ADRs are rarely needed afterwards, but when they are (mostly during onboarding of new team members, but maybe also if something doesn't turn out the way we imagined), they are an immensely useful tool for understanding the thinking that went into the decision.
In other words (because I've been thinking about Peter Naur's Theory Building View lately), ADRs can help people (re)build the theory of the system in their minds if necessary, keeping it alive. People who already possess the theory don't need to read them, and this is a good thing.
I recently added the #knowledge vault to my website with a new article: #ADRs (Architecture Decision Records). Why isn’t this in the blog? The vault is designed to collect information together in long-form reference articles, whereas the blog posts are shorter or more transitory (but still useful!).
What do you think of the ADRs article? What topics would you like me to cover in the knowledge vault?
Vault: https://jacquiread.com/knowledge/?utm_source=Mastodon&utm_medium=Social&utm_content=mastodon-link&utm_campaign=professional&id=lJbkAM1Wa
ADRs article: https://jacquiread.com/knowledge/adrs/
Within this section of the website you will find information on various topics from around the IT industry. They differ from blog posts in that they are more of an overview of a topic, from which you can then move on to reading blog posts, identifying books, or scheduling workshops. The collection will grow over time.
avoid mixing levels of abstraction.
But can you take this too far? Absolutely. It is usually adequate to split a high-level criterion into no more than 3-4 lower-level criteria, but as usual it depends on the scope and complexity of your ADR.
What has worked best for you?
I’ll be sharing more on #SoftwareArchitecture, #ADRs, and #SoftwareDiagraming so if you got value from this post please 🔔 follow and 🔗 share.
(Image from my book, Communication Patterns, @OReillyMedia).
5/5
News e você
Nicolas Fränkel 🇪🇺🇺🇦🇬🇪
JCON
Thomas Byern
InfoQ
Sebastian Hans
Jacqui Read