Architectural Decision Records (ADRs) (2018) | Hacker News Reader

Architectural Decision Records (ADRs) (2018)

adr.github.io

89 pointskornish17 comments

There is a nice discussion around a GitHub blog post about them from 6 months ago: https://news.ycombinator.com/item?id=24146594

This could give some context to people hearing about ADRs for the first time

I tried using these multiple times (I even know a contributor to this endeavour) but I always struggled with what the scope should be.

For a little bit of context, I work with server architecture in a role that used to be defined as sysadmin, then devops and now SRE.

But there’s many decisions a day and there is a huge trade off in having many records (which become essentially write-only as nobody will trawl through) or too few (which leave some gaps or become very large).

Has anyone found a good threshold for what should be a new ADR from an ops perspective.

"Based on my experience in this area and with this business, will I likely be asked about this later and will I confidently and easily be able to answer? Is the expected value of recording higher than the expected value of not (factoring in time, noise, mental load later etc)?" is something like what I ask myself to help decide. Also if you make it filterable and searchable (table instead of document format) you can minimise the issues of having a lot of them. You can add your own scale/importance tags as well to give a list of overview ones to read through too.

We just started using these at my job. I like how the approach takes the conversation out of a slack thread and generates some documentation to boot. The tooling ecosystem is also excellent (adr-tools is awesome) and you can easily integrate stuff like confluence document generation as part of your ci pipeline.

We've taken the approach of submitting adrs as a pull request on the repo they affect (we have a dedicated repo for higher level adrs) and submit the link to a dedicated slack channel so folks can have a look and submit any comments they might have on the proposed decision. Once everything has been hashed out, we either merge the PR and get busy implementing the idea or close out the PR and move on.

I started using something like these a little while back and they're phenomenal. Nothing like being able to answer "what the hell was I thinking 6 months ago?", or a stakeholder's "why are we doing it this way?". Also great for getting a new contributor up to speed. My preferred format is a simple Excel table: ID, Date, Area, Decision, Reason, People Involved.

I first learned about ADRs in a course led by Michael Nygard, author of the book Release It (https://pragprog.com/titles/mnee2/release-it-second-edition/). Since then, I've seen them used well by our Platform Team (Scaling/SRE/Infra), but our product teams have not adopted.

Interesting to also read Nygard's post from 2011 on ADRs: https://www.cognitect.com/blog/2011/11/15/documenting-archit...

Regardless of whether one chooses to use ADRs or not, recording the factors that went into a major decision is a great practice which can help counter the tendency to use Resulting. That is, we have a tendency to judge whether or not a decision was sound based on the outcome, rather than all the factors and conditions that made up the decision at the time we were making it.

How do RFCs and ADRs play together? Would you consider a finalized RFC (all comments/concerns addressed in some way) to be an ADR?

We use at both in my department at work. They is some overlap, but since each have different strengths I think they work well together.

RFCs are great for capturing discussions and exploring ideas in depth. You can get deep into the details if needed. ADRs are all about capturing a decision. They should capture the important bits of context and consequences, but without a huge amount of detail.

In terms of the process for producing these documents, if a decision is straightforward we will go straight to writing an ADR. If there are multiple options or we want to explore some corner cases, we'll start with an RFC. An ADR is often part of he output of an RFC which reaches consensus, but not always. Related RFCs and ADRs include links to one another.

If people are looking to get up to speed on something, their first port of call is the ADRs. If they have concerns, disagree with a past decision, or simply want to know more then they can dig into the RFCs.

I'm interested in those kind of software related processes documentation approaches. If you have other similar things I would be happy to check them out.

I use Python PEPs for architecture decision logs

Anyone know of any OSS projects that are using ADRs?

I'd love to see some examples of them being used in the wild.

Yes this open source repo:

https://github.com/joelparkerhenderson/architecture_decision...

See the `examples` directory for real ADRs, such as for CSS frameworks (e.g. Bulma), secrets storage (e.g. Bitwarden, Vault), programming language stack (e.g. Typescript, Rust), etc.

https://github.com/backstage/backstage

Makes it easy to understand the reasoning behind a lot of decisions.

I haven’t seen backstage before and it looks awesome. Thanks!

https://github.com/oasisprotocol/oasis-core/tree/master/docs...

This one was my first exposure to ADRs. I liked how they went with something standard instead of doing the blockchain traditional X Improvement Proposal (BIP, EIP).

IMHO Architecture is a too vague term, there can be many decisions that will be user facing and that doesn't alter the "overall architecture" of the software. Calling them Technical decisions records or simply decision records would be better and less cargo-culting prone.

Reply on news.ycombinator.com