
Why Write ADRs - imsky
https://github.blog/2020-08-13-why-write-adrs/
======
rabidrat
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.

~~~
aplummer
> 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.

~~~
dfcowell
This is fundamentally missing the point about what story points are, and goes
to show you’re unfortunately stuck in another of the many companies using them
poorly.

Many (poor) product managers look at velocity dropping and blame the team, or
try to pack sprints. In fact, this is the time to open dialogue with the team
and get to the bottom of why.

Often, it’s because tech debt or poor architecture is making it difficult to
implement even simple features. The team might be burning out. There might be
an overwhelming number of bugs and support tickets that need to be addressed.

Story points aren’t a target to hit, or even a KPI. They’re a barometer for
team and process health. Unfortunately most engineering and product managers
either don’t get it, or are unable to appropriately communicate that fact
upwards.

------
Pxtl
I think whether you use adrs or comments or git messages or readmes or
whatever, the fundamental rule is simple:

In any case where you're making a non-default choice in software, it needs to
be explained in an easily-discoverable place so a developer that's looking at
the project and trying to understand the _why_ of something can see it.

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 "no, I'm
not attacking your code as being wrong, and I don'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".

...

But actually usually the code is just wrong.

------
sbuttgereit
This is far from the first time I've evangelized this paper here on HN... but
I think the ideas of the OP and the Naur paper "Programming as Theory
Building" 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.

[http://pages.cs.wisc.edu/~remzi/Naur.pdf](http://pages.cs.wisc.edu/~remzi/Naur.pdf)

~~~
jonnydubowsky
Thanks for the recommendation! Already enjoying this!

~~~
usrme
There are also plain text versions of that paper if you're interested:

\- [https://pastebin.com/raw/WwXKAGnW](https://pastebin.com/raw/WwXKAGnW)

\-
[https://gist.github.com/onlurking/fc5c81d18cfce9ff81bc968a7f...](https://gist.github.com/onlurking/fc5c81d18cfce9ff81bc968a7f342fb1)

------
vemv
Quite ironically (given it'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/PRs, etc) and try to ping the team for feedback.

The design process will ideally happen asynchronously, as comments posted in
the issue.

That way, a truthful trail of diverse considerations will be left in written
form.

Contrariwise, ADRs can be too written excessively after-the-fact, by a single
person. I have seen them degenerate into bureaucracy ("we designed X because X
seemed the best option"... how informative).

~~~
dllthomas
> "we designed X because X seemed the best option"... how informative

If that's the most they can say, I'd rather that be surfaced. Knowing the
decision was made in haste, with shallow consideration, is better than
wondering if it was. And actually, that's probably the right way to make some
decisions, if they seem likely to have a small difference in value between the
many options it doesn't make a lot of sense to burn too many cycles making
sure of that.

Once decisions come around to bite you, you can start to look at whether the
decisions that are _actually_ proving costly were the ones that were made
lightly.

At least, that's how I'm thinking about it before getting into the weeds of
it.

------
linux2647
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.

~~~
dglass
I started a new job about two months ago and completely agree. The ADRs and
Feature Specs have been immensely helpful in getting context around why
certain decisions were made and the tradeoffs considered when making
decisions.

It's especially useful because I joined the team during Covid and haven't
actually met anyone else in person yet. I can't just turn around in my chair
and ask someone at the desk next to me why something is the way it is. Now it
involves pinging someone, setting up a zoom call, etc.

~~~
zimpenfish
I joined a place recently and there was zero documentation, zero ADRs, zero
discussions logged except vaguely in Slack, etc. Consequently I was completely
baffled about why everything was as it is for the first few months ("Where do
I find a network?" "It's in the frobnob_stash table under 'lemon'." "Oh, yeah,
OBVIOUSLY.")

------
jayd16
So this is somewhere between code comments and Confluence pages. Seeing as
even comments can get stale, how accurate do these docs stay?

The added focus on "why" instead of "what" seems more resistant to cruft.

~~~
coldtea
> _Seeing as even comments can get stale, how accurate do these docs stay?_

Part of the idea is that they're immutable, append-only. They express why an
architecture / decision was made, when it was made.

~~~
dllthomas
Not that it takes anything away from your point, but to be slightly more
precise, the content should (probably, see below) be treated as immutable. The
metadata, included in the same files, is mutable - things like status, related
ADRs, superseding PRS, etc.

Above I said probably - I'm not _sure_ that we shouldn't allow editing when
it's purely clarification, communicating more clearly what it already
communicated to most of the audience.

An append-only section for adding further observations, as the decision plays
itself out, is also an interesting option, although I don't know whether it
would actually be more valuable than distracting.

------
BillSaysThis
Shout out to my pal Joel, who was in this space for awhile already!
[https://github.com/joelparkerhenderson/architecture_decision...](https://github.com/joelparkerhenderson/architecture_decision_record)

------
jsdalton
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.

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).

I’d be interested in thoughts or experience people have, especially in medium
or larger organizations.

~~~
qznc
I'm the software architect in a automotive project with ten teams. We use
Confluence to write ADRs. We only use this process for changes which affect
multiple teams.

Pro: Wysiwyg is great for editing it live in meetings, plugins like Gliffy are
nice for diagrams, integration with Jira, accessible with a simple link.

Con: Not good enough for long term archival, so we export them to pdf
regularly, wiki has no atomic commits.

We have a regular meeting where the team architects together discuss and
ultimately approve these documents.

------
arcticbull
I'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've introduced this at a few places I've worked and it's been very well
received.

[1] [https://firstround.com/review/square-defangs-difficult-
decis...](https://firstround.com/review/square-defangs-difficult-decisions-
with-this-system-heres-how/)

~~~
dangoor
At Khan Academy, we've been using ADRs for three years now, using Michael
Nygard's format as a starting point. We adopted ADRs at the same time we
adopted DACI (Driver, Approver, Contributors, Informed) as a decision making
framework across the organization, so our ADRs server both of these purposes
as well.

------
draven
We use Kanban in my organisation and tickets go through a Analysis phase where
the dev spells out the technical details of what they'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.

It may seem a lot of overhead at first but the team is small and tickets go
through these two phases fast.

The analysis can be considered sort of an ad-hoc ADR.

We started this quite recently but it's already useful and did not slow us
down.

~~~
dllthomas
It's related, but I think it's not quite the same thing. It sounds like you
are describing the intended design of the feature you're implementing. As I
understand it, an ADR may also set policy regarding future features, where
they touch an architectural concern.

------
cosmic_quanta
I 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!

~~~
Inversechi
A community that I've seen doing this pretty well is the Home Assistant
community. You might wanna check their examples out.

[https://github.com/home-assistant/architecture](https://github.com/home-
assistant/architecture)

------
timwis
I’m hoping to implement this in my organisation very soon. There are still a
couple things I need to figure out:

1\. How do I articulate the criteria for _when_ a decision should have an ADR?

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?

Any advice?

~~~
willejs
1\. I usually advise people to raise an ADR when they are adding new component
to a system, a new technology, or really anything that they feel needs context
and want to have a discussion about. Usually I advise either making a pr in
the repo for that component (this can be in #1 with the first commits of code)
or in a centralised docs repo when you are adding new technologies to your
stack or setting standards etc. 2\. I have used them in place of RFCs at a
couple of places. Generally I would write code or docs alongside an ADR and
use the comments in a pull request to get a review on it, and try to improve
the PR with the comments. If there is a consensus in the PR from enough people
it would get merged in, if not i would take it to an appropriate forum to
discuss it (guild, standup, meeting etc).

I have found creating a couple of ADRs in a team and getting that team to
participate in the process first is a great example to showcase to an
organisation at a show and tell, lunch and learn etc. Adr-tools is a great
tool to help create an ADR and provides a good template too!

------
euske
I think the fundamental idea behind this is that "every decision must be
rationalized", which is fine, but in reality it's difficult to pull off in my
opinion. Because people (including myself) are so easily fooled, I'm afraid
that it'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.

~~~
dasil003
Not sure about that. Writing software requires heavy rationalization just to
get a minimally working system. This is one reason some people aren't cut out
to be programmers—they just don't have to patience to deal with the pedantic
requirements of implementing cold, hard, unambiguous system logic.

I think it's more about _documentation_ of that rationalization, and I
wouldn't want to raise the bar on this by requiring a review. The value of
every engineer just braindumping the roughest cut of their thinking already
provides a tremendous amount of value over the history of a long-lived code
base. Personally I do this in commit messages even for solo projects, but for
larger teams/code bases/SOAs a more formal document-based approach allowing
for diagrams and additional metadata is highly valuable if done consistently.

~~~
dllthomas
Rationalization or reasoning? I'm not sure which you're talking about, and the
meaning of your text winds up being pretty different in each case. I'm not
sure I disagree with either.

------
iainmerrick
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 _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...](https://github.com/joelparkerhenderson/architecture_decision_record)
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.

~~~
codesuki
I came to the same conclusion. I wanted to write ADRs since the first time I
read about them a few years back. Thinking more about it I concluded that
commit messages are the right place to document this. You can find the commit
for a line of code and you can just read git log.

If people tried both and have opinions please share. So far I am ok with
commit messages even if they tend to be long.

Another thing. How do you people think ADRs compare to design docs? IMO design
docs are for gathering feedback and ADRs are for documenting decided things,
there is some overlap.

~~~
resonator
Most of the changes we (I work in a platform team) make may perhaps only
modify a couple of lines of code, but took significant time and effort to
reach.

As an example, we recently decided to adopt the use of Kubernetes CPU manager.
The actual change was modifying the resource requests for some applications.
That part of the code is highly dynamic as apps change and are retuned over
time. To store the decision to use CPU manager in a commit message or even a
Github PR would not be appropriate -- it's discoverability is too low compared
to its importance.

Unlike Git commits or PRs, our ADRs are a rich archive of well thought out
decisions with all the rationale that went into making them. We can easily see
which ones remain relevant. But what I think is the most important is we have
all the information we need to change our decisions and we do. We no longer
fear making change because we might not have all the context, or we forgot, or
the person who made the decision quit last year.

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

~~~
usrme
Wholly agree with you. That's what I'm always hoping for when big company X
does a blog post about thing Y, that they actually show some examples about
how they have implemented thing Y as otherwise the post falls a bit flat (for
me).

------
brainzap
When Should I Write an Architecture Decision Record
[https://engineering.atspotify.com/2020/04/14/when-should-
i-w...](https://engineering.atspotify.com/2020/04/14/when-should-i-write-an-
architecture-decision-record/)

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

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

