Why Write ADRs
github.blog
Why Write ADRs
1–10 of 64 posts
Re: Why Write ADRs
#2I had never heard of ADRs, but now I see that I've been putting some of the information in comments or module-level docs. I'll definitely look into the linked examples!
Re: Why Write ADRs
#3These 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.
Re: Why Write ADRs
#4I had never heard of ADRs, but now I see that I've been putting some of the information in comments or module-level docs. I'll definitely look into the linked examples!
A community that I've seen doing this pretty well is the Home Assistant community. You might wanna check their examples out.
Re: Why Write ADRs
#5Shout out to my pal Joel, who was in this space for awhile already! https://github.com/joelparkerhenderson/architecture_decision...
Re: Why Write ADRs
#6I 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.
Re: Why Write ADRs
#7The 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 won’t find it on its own and be unsure whether it’s still relevant.
When it’s part of the git history, the history itself tells you whether those changes stuck around or were superseded.
Checking the original post to make sure I’m not just repeating it, I don’t think I am -- it links to https://github.com/joelparkerhenderson/architecture_decision... which proposes a whole bunch of acronyms (ADL, ADR, AKS, ASR) but doesn’t offer an opinion on where they should be stored! This is bureaucracy for bureaucracy’s sake, missing the wood for the trees.
Edit to add: 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...?)
TL;DR: we don’t need a whole new set of complex workflows for this, we just need good commit messages.
Re: Why Write ADRs
#8The 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 won’t find it on its own and be unsure whether it’s still relevant. When it’s part of the git history, the history itself tells you whether those changes stuck around or were superseded. Checking the ori…
so what would the experience be for someone new joining the project, particular if you have many repositories? having to search across numerous repositories? In practice I've found this (source control commit messages as ADR's) doesn't work. Unless I have mistaken what you have said? I just keep a repository for ADR's, which can then be published to a wiki or else where.
Re: Why Write ADRs
#9These 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…
> But make sure you also get your story points done for this sprint and meet your OKRs for this quarter.
The problem here is the points aren't measuring quality, they are measuring a type of velocity that doesn't take into account quality if you aren't getting points for that work.
Read: PMs often drive a timeline that accepts engineering risk, but not responsibility for that decision when it doesn't work.
Re: Why Write ADRs
#10The 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 won’t find it on its own and be unsure whether it’s still relevant. When it’s part of the git history, the history itself tells you whether those changes stuck around or were superseded. Checking the ori…
so what would the experience be for someone new joining the project, particular if you have many repositories? having to search across numerous repositories? In practice I've found this (source control commit messages as ADR's) doesn't work. Unless I have mistaken what you have said? I just keep a repository for ADR's, which can then be published to a wiki or else where.
In that situation, I think the best layout is:
- your centralised wiki lists all the repositories and explains what they’re for;
- each repository has a detailed commit history, allowing you to understand the thinking behind each line of code.
Edit to add: you can search across multiple repos with Github’s “search in organization” feature, and it actually works very well. I usually find that much more useful than searching through a wiki that’s separate from the code (although maybe I just haven’t ever seen a wiki that was sufficiently well organized?)