There is a nice discussion around a GitHub blog post about them from 6 months ago: <a href="https://news.ycombinator.com/item?id=24146594" rel="nofollow">https://news.ycombinator.com/item?id=24146594</a><p>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.<p>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.<p>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).<p>Has anyone found a good threshold for what should be a new ADR from an ops perspective.
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.<p>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 (<a href="https://pragprog.com/titles/mnee2/release-it-second-edition/" rel="nofollow">https://pragprog.com/titles/mnee2/release-it-second-edition/</a>). Since then, I've seen them used well by our Platform Team (Scaling/SRE/Infra), but our product teams have not adopted.<p>Interesting to also read Nygard's post from 2011 on ADRs: <a href="https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions" rel="nofollow">https://www.cognitect.com/blog/2011/11/15/documenting-archit...</a>
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.
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.
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.