Why Write ADRs

These articles about engineering process always put the responsibility solely in the implementing engineer's lap. Always more and more work to achieve JPL-level capability maturity, no matter your budget or headcount. Of course we want unit tests for every case, and verbose explanation in every atomic commit message, and architecture documents that are seldom read before they become stale. But make sure you also get your story points done for this sprint and meet your OKRs for this quarter.

I think whether you use adrs or comments or git messages or readmes or whatever, the fundamental rule is simple:<p>In any case where you&#x27;re making a non-default choice in software, it needs to be explained in an easily-discoverable place so a developer that&#x27;s looking at the project and trying to understand the <i>why</i> of something can see it.<p>Too often I block PRs with confusing code and ask why it was done this way and the developer swings by my office or gets defensive and I have to say &quot;no, I&#x27;m not attacking your code as being wrong, and I don&#x27;t want a verbal explanation as to how it works. I want the decisions that led you to do it this way to be documented&quot;.<p>...<p>But actually usually the code is just wrong.

This is far from the first time I&#x27;ve evangelized this paper here on HN... but I think the ideas of the OP and the Naur paper &quot;Programming as Theory Building&quot; have a high degree of overlap. Indeed, at some level, the Naur paper deals with identifying the problem while the OP deals with practices to bridge the knowledge gap identified in the paper.<p><a href="http:&#x2F;&#x2F;pages.cs.wisc.edu&#x2F;~remzi&#x2F;Naur.pdf" rel="nofollow">http:&#x2F;&#x2F;pages.cs.wisc.edu&#x2F;~remzi&#x2F;Naur.pdf</a>

Quite ironically (given it&#x27;s Github who are defending ADRs in the article), I avoid ADRs by using Github more richly: before working on a branch at all I create a substantial issue (think: multiple paragraphs, links to related issues&#x2F;PRs, etc) and try to ping the team for feedback.<p>The design process will ideally happen asynchronously, as comments posted in the issue.<p>That way, a truthful trail of diverse considerations will be left in written form.<p>Contrariwise, ADRs can be too written excessively after-the-fact, by a single person. I have seen them degenerate into bureaucracy (&quot;we designed X because X seemed the best option&quot;... how informative).

I started a new job about six months ago and the engineering org writes ADRs. As a new hire, this was incredibly useful to understand some of the hows and whys of past decisions that would normally take me years to discover or understand.

So this is somewhere between code comments and Confluence pages. Seeing as even comments can get stale, how accurate do these docs stay?<p>The added focus on &quot;why&quot; instead of &quot;what&quot; seems more resistant to cruft.

Shout out to my pal Joel, who was in this space for awhile already! <a href="https:&#x2F;&#x2F;github.com&#x2F;joelparkerhenderson&#x2F;architecture_decision_record" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;joelparkerhenderson&#x2F;architecture_decision...</a>

The “whys” here all sound sensible, but I’d be even more interested in _how_ people are implementing a process around ADRs, where you’re keeping them, etc.<p>At work we have a decent PR template that prompts people to provide context, alternatives considered, and underlying reasons for the change, which works pretty well. I’m trying about how or whether ADRs would function better, or if they would operate at a slightly higher level of change (i.e. for work that extends across multiple PRs).<p>I’d be interested in thoughts or experience people have, especially in medium or larger organizations.

I&#x27;m personally a huge fan of the SPADE framework from Gokul Rajaram. First Round has a really good write-up on how to use it. [1] It serves both as an ADR and also a framework for making that decision in the first place, in one. I&#x27;ve introduced this at a few places I&#x27;ve worked and it&#x27;s been very well received.<p>[1] <a href="https:&#x2F;&#x2F;firstround.com&#x2F;review&#x2F;square-defangs-difficult-decisions-with-this-system-heres-how&#x2F;" rel="nofollow">https:&#x2F;&#x2F;firstround.com&#x2F;review&#x2F;square-defangs-difficult-decis...</a>

I’m hoping to implement this in my organisation very soon. There are still a couple things I need to figure out:<p>1. How do I articulate the criteria for <i>when</i> a decision should have an ADR?<p>2. I always see ADRs in the context of recording what was decided, but I’d like them to be raised more like requests for comments (RFCs) for a week or two first, particularly in cases where there may be impacts on other systems, security or data protection implications. Are ADRs often used this way, or should I be looking at something else?<p>Any advice?

We use Kanban in my organisation and tickets go through a Analysis phase where the dev spells out the technical details of what they&#x27;re going to do and then an Analysis review where two other devs will validate the analysis. Then the ticket can move to the implementation phase itself.<p>It may seem a lot of overhead at first but the team is small and tickets go through these two phases fast.<p>The analysis can be considered sort of an ad-hoc ADR.<p>We started this quite recently but it&#x27;s already useful and did not slow us down.

I had never heard of ADRs, but now I see that I&#x27;ve been putting some of the information in comments or module-level docs. I&#x27;ll definitely look into the linked examples!

I think the fundamental idea behind this is that &quot;every decision must be rationalized&quot;, which is fine, but in reality it&#x27;s difficult to pull off in my opinion. Because people (including myself) are so easily fooled, I&#x27;m afraid that it&#x27;s often the case that we deliberately ignore certain (inconvenient) facts or unconsciously distort things. If we are really trying to rationalize ourselves, the decisions have to be reviewed by multiple people.

The basic idea is good, but isn’t a commit message the best place for this? That will ensure that people will find it when looking through source control history to understand some code, but equally importantly, they <i>won’t</i> find it on its own and be unsure whether it’s still relevant.<p>When it’s part of the git history, the history itself tells you whether those changes stuck around or were superseded.<p>Checking the original post to make sure I’m not just repeating it, I don’t think I am -- it links to <a href="https:&#x2F;&#x2F;github.com&#x2F;joelparkerhenderson&#x2F;architecture_decision_record" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;joelparkerhenderson&#x2F;architecture_decision...</a> which proposes a whole bunch of acronyms (ADL, ADR, AKS, ASR) but doesn’t offer an opinion on <i>where</i> they should be stored! This is bureaucracy for bureaucracy’s sake, missing the wood for the trees.<p><i>Edit to add:</i> I’m not quite right, it does offer an opinion; it suggests text files in an “adr” directory. For the reasons outlined above I think this is both more and less than you need. (Maybe there should be an ADR for the location of the ADR directory...?)<p>TL;DR: we don’t need a whole new set of complex workflows for this, we just need good commit messages.

They could have included some nice examples from GitHub themselves in this blog article.

When Should I Write an Architecture Decision Record <a href="https:&#x2F;&#x2F;engineering.atspotify.com&#x2F;2020&#x2F;04&#x2F;14&#x2F;when-should-i-write-an-architecture-decision-record&#x2F;" rel="nofollow">https:&#x2F;&#x2F;engineering.atspotify.com&#x2F;2020&#x2F;04&#x2F;14&#x2F;when-should-i-w...</a>

yet another name for documentation nobody will write, but the manager will be able to say &quot;solved the lack of documentation this quarter by implementing XYZ&quot;.

Thought this was going to be about American Depositary Receipts. Was disappointed... :(