#adrs — Public Fediverse posts

Tip #1: For every PR, document the relevant architecture decisions using Architecture Decision Records (ADRs). This way, when scaling issues start to hurt around the sixth month, you can trace the problems back to a specific decision. Otherwise, you’ll only remember that “this felt terrible” rather than understanding that “putting X in the router made Y expensive.” This is how you build a real understanding of the architecture over time. #iOS #Swift #architecture #ADRs

Your #architecture decision records capture what was decided and why. They don't capture what you believed was true at the time. When an assumption breaks — "users will do this" — how do you find every decision built on that belief? Re-read all 300 #ADRs & pray? https://www.attilagyorffy.com/blog/the-assumption-nobody-wrote-down/

How to Make #Architecture Decisions: #RFCs, #ADRs, and Getting Everyone Aligned

https://lukasniessen.medium.com/how-to-make-architecture-decisions-rfcs-adrs-and-getting-everyone-aligned-ab82e5384d2f

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

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

#InfoQ #QConSF #ADRs #TechLeadership #Culture

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.

#softwarearchitecture #documentation #ADRs

@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.

#softwarearchitecture #ADRs

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/

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

3/3
Be careful though, some of these constraints can be sensitive topics, such as having to follow a company master solution, or that the team does not have the skills to implement an option. Keep your ADR impartial. You should assume anybody in your organisation could read it.

I’ll be sharing more on #SoftwareArchitecture, #ADRs, and #SoftwareDiagraming so if you got value from this post please 🔔 follow and 🔗 share.

Sonya Natanzon is giving some great reasons why #SoftwareArchitecture decisions are important at #gsas

#gsas23 #why #ADRs

Cool finding that they used #ADRs :) https://cloak.software/blog/i-built-startup-in-rust/