An engineering blog post is written after the decision, often after the system has been running long enough to collect success metrics. An ADR is written at the time of the decision, before the outcome is known. This temporal difference means ADRs contain something blog posts rarely do: honest uncertainty, documented assumptions, and explicit acknowledgment of what the team didn't know.
Architecture decision records are short documents — typically one to two pages — that describe a significant architectural decision, the context that drove it, the options that were considered, the option that was chosen, and the consequences the team expected. Companies that maintain public ADR repositories give outsiders a form of access that no blog post provides: the actual reasoning process, not the retrospective rationalization.
Shopify, GitHub, and Spotify have all published or discussed their ADR practices. The format varies — some teams follow Michael Nygard's original template closely, others adapt it — but the core content is consistent. Understanding what to look for in each section makes ADRs dramatically more useful as a learning resource.
What to read in the context section
The context section of an ADR describes why a decision needed to be made at this particular moment. This is the constraint statement, and it's the single most important part of the document for external readers.
A context section that says "our monolith was getting harder to deploy" is weak. A context section that says "our deployment pipeline required 45 minutes of testing before a single service could deploy, and we were making 12 deploys per day across 6 services, which meant engineers were waiting up to 90 minutes to see their changes in production" is strong — it names the constraint with enough specificity that you can assess whether the same constraint applies to your context.
The constraint in the context section also tells you what the decision was optimizing for. An ADR that says "we need to reduce coordination between teams" is optimizing for organizational autonomy. One that says "we need to reduce infrastructure costs" is optimizing for unit economics. The same architectural decision — say, moving from a shared database to per-service databases — can be the right answer to both constraints, but the implementation details differ, and the tradeoffs that mattered differ, and the lessons that transfer to your context differ.
The rejected alternatives section: where the real learning is
Most engineers who read ADRs focus on the decision that was made and skim the rejected alternatives. This is backwards. The rejected alternatives section is where the architectural thinking is most visible, because it shows the option space the team considered and documents why each option was insufficient.
A rejected alternative entry that says "we considered GraphQL but went with REST" is not useful. A rejected alternative entry that says "we evaluated GraphQL but rejected it because our mobile clients needed to minimize battery and data usage on 3G connections, and the query flexibility of GraphQL would have made response size unpredictable without additional tooling investment we weren't prepared to make" is extremely useful — it shows what specific concern drove the rejection.
Rejected alternatives that were seriously considered often include experiments or prototypes that were built and abandoned. These are particularly valuable because they represent real work that produced a negative result — something almost never documented in retrospective blog posts, which tend to describe only the path that succeeded. Finding an ADR that says "we built a prototype of approach X and found problem Y" tells you something that might take your team months to discover independently.
The rejected alternatives section of a strong ADR is more useful than the conclusion. It shows the option space the team saw, the criteria they applied, and what specifically failed. Read it first.
Reading the consequences section honestly
The consequences section of an ADR describes what the team expected to happen as a result of the decision — both good and bad. This is the section that becomes most interesting over time, because teams that revisit and update their ADRs create a record of whether their predictions were accurate.
A consequences section written honestly contains negative consequences the team accepted. "This decision means that queries spanning multiple services will require application-level joins, which adds complexity to any feature that needs to aggregate data across domain boundaries" is a team acknowledging a real cost. A consequences section that lists only benefits is either optimistic to the point of dishonesty or was written after the fact to justify a predetermined conclusion.
When reading ADRs from public repositories, look for whether the consequences section was ever updated with a retrospective note. Some teams add a status field — "Accepted", "Superseded", "Deprecated" — and a note explaining what changed. A superseded ADR with a note that says "this decision was reversed in ADR-047 because the assumed team growth didn't materialize and the operational overhead exceeded the autonomy benefit" is one of the most instructive documents an external engineer can read.
How to use ADR sequences to understand system evolution
A single ADR describes a single decision. A sequence of ADRs from the same system describes the evolution of a codebase over time — how early assumptions were validated or invalidated, how constraints changed as the system scaled, and which architectural patterns were adopted, found insufficient, and replaced.
Reading a sequence of ADRs from a specific system is more instructive than reading isolated posts from many systems. When you can see that ADR-003 chose eventual consistency for a specific reason, and then ADR-019 replaced that approach because the reason in ADR-003 turned out to be wrong, you're seeing something that no individual post about eventual consistency can teach: the specific conditions under which that tradeoff fails in production.
Teams that maintain numbered ADR sequences with clear references between documents — "this ADR supersedes ADR-007" or "this decision builds on the constraints established in ADR-012" — are essentially publishing a living document of their architectural reasoning. Finding and reading one of these sequences is one of the highest-leverage uses of time available in engineering self-education.