I'd love to see some examples of them being used in the wild.
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.
Makes it easy to understand the reasoning behind a lot of decisions.
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).
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.
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.
This could give some context to people hearing about ADRs for the first time
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.
Interesting to also read Nygard's post from 2011 on ADRs: https://www.cognitect.com/blog/2011/11/15/documenting-archit...
