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.
Why Write ADRs
21–30 of 64 posts
Re: Why Write ADRs
#22These 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…
I've been intrigued by ADRs for a bit, and this post prompted me to start a conversation with my current team. Quoting something I posted in my internal slack:
> Note that my goal, with ADRs, is not to increase the amount of time we spend on decisions! If the answers are "I didn't think too deeply and I'm going with my gut" it's still better to have that documented. If we find that we're getting bit by bad decisions, we can look at how those decisions were made and how we can improve them at that point, with much more context.
Re: Why Write ADRs
#23I 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 rev…
I would agree that ADRs are not really necessary if you work alone. Maybe not even within a team if it stable over a long time.
Where ADRs are helpful is when many teams cooperate and if people come and go. The reviews happen implicitly because the decision is discussed among many people.
Re: Why Write ADRs
#24This 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
Thanks for the recommendation! Already enjoying this!
Re: Why Write ADRs
#25The 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…
I'm the repo maintainer. To answer your questions...
I recommend storing the ADRs as text files in a directory, such as `doc/adr`, or if you prefer words then `documentation/decisions`. Some teams prefer to use a wiki, or CMS, etc. and that can work well too.
I do recommend decision records as separate from git commit messages:
1. Easier for people to create, read, search, manage, sync, and audit. We use simple text formats, such as markdown.
2. Easier to generalize to multiple areas. For example, we use quick decision records to evaluate practices, tools, and techniques, across multiple projects and organizations. Participants don't always have access to the same git repos, and some participants don't even know git (e.g. finance, hard science companies, large enterprises).
3. Easier to update/append/eol when new information arrives. We revisit our decision records, such as when new technologies come into play, or when new requirements are created, or when we grow and want scalability, security, stability, etc. Appending to a text file is a piece of cake.
Re: Why Write ADRs
#26I 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.
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.
Re: Why Write ADRs
#27The 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…
If you make a habit of browsing your git log with -p or --numstat, you'll see the changes to the ADR show up.
> be unsure whether it’s still relevant.
The idea is that it's still relevant unless it's been marked superceded or deprecated.
> the history itself tells you whether those changes stuck around or were superseded.
Not really. The history has all of the changes, interleaved. So it's not easy for, looking at a commit message way in the past, to know whether a decision described there still applies to some later version.
Re: Why Write ADRs
#28So 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.
> 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.
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.
Re: Why Write ADRs
#29The 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…
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…
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.
Re: Why Write ADRs
#30I 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 rev…
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.