5 ms·

Architectural Decision Records (ADRs) (2018)

89 points by kornish 6y ago

mountaineer 6y ago
I first learned about ADRs in a course led by Michael Nygard, author of the book Release It (https://pragprog.com/titles/mnee2/release-it-second-edition/ https://pragprog.com/titles/mnee2/release-it-second-edition/). Since then, I've seen them used well by our Platform Team (Scaling/SRE/Infra), but our product teams have not adopted. Interesting to also read Nygard's post from 2011 on ADRs: https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions https://www.cognitect.com/blog/2011/11/15/documenting-archit...
sdfhbdf 6y ago
There is a nice discussion around a GitHub blog post about them from 6 months ago: https://news.ycombinator.com/item?id=24146594 https://news.ycombinator.com/item?id=24146594 This could give some context to people hearing about ADRs for the first time
GordonS 6y ago
Anyone know of any OSS projects that are using ADRs? I'd love to see some examples of them being used in the wild.
- _nhynes 6y ago
  https://github.com/oasisprotocol/oasis-core/tree/master/docs/adr https://github.com/oasisprotocol/oasis-core/tree/master/docs... This one was my first exposure to ADRs. I liked how they went with something standard instead of doing the blockchain traditional X Improvement Proposal (BIP, EIP).
- jph 6y ago
  Yes this open source repo: https://github.com/joelparkerhenderson/architecture_decision_record https://github.com/joelparkerhenderson/architecture_decision... See the `examples` directory for real ADRs, such as for CSS frameworks (e.g. Bulma), secrets storage (e.g. Bitwarden, Vault), programming language stack (e.g. Typescript, Rust), etc.
- draklor40 6y ago
  https://github.com/backstage/backstage https://github.com/backstage/backstage Makes it easy to understand the reasoning behind a lot of decisions.
  - doctor_eval 6y ago
    I haven’t seen backstage before and it looks awesome. Thanks!
ryeguy 6y ago
How do RFCs and ADRs play together? Would you consider a finalized RFC (all comments/concerns addressed in some way) to be an ADR?
- vaughandroid 6y ago
  We use at both in my department at work. They is some overlap, but since each have different strengths I think they work well together. RFCs are great for capturing discussions and exploring ideas in depth. You can get deep into the details if needed. ADRs are all about capturing a decision. They should capture the important bits of context and consequences, but without a huge amount of detail. In terms of the process for producing these documents, if a decision is straightforward we will go straight to writing an ADR. If there are multiple options or we want to explore some corner cases, we'll start with an RFC. An ADR is often part of he output of an RFC which reaches consensus, but not always. Related RFCs and ADRs include links to one another. If people are looking to get up to speed on something, their first port of call is the ADRs. If they have concerns, disagree with a past decision, or simply want to know more then they can dig into the RFCs.
- deleted 6y ago
  [deleted]
The_rationalist 6y ago
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.
vikingcaffiene 6y ago
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. 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.
GSGBen 6y ago
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.
dijit 6y ago
I tried using these multiple times (I even know a contributor to this endeavour) but I always struggled with what the scope should be. 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. 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). Has anyone found a good threshold for what should be a new ADR from an ops perspective.
- GSGBen 6y ago
  "Based on my experience in this area and with this business, will I likely be asked about this later and will I confidently and easily be able to answer? Is the expected value of recording higher than the expected value of not (factoring in time, noise, mental load later etc)?" is something like what I ask myself to help decide. Also if you make it filterable and searchable (table instead of document format) you can minimise the issues of having a lot of them. You can add your own scale/importance tags as well to give a list of overview ones to read through too.
ta988 6y ago
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.
- flarg 6y ago
  I use Python PEPs for architecture decision logs
baconforce 6y ago
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.

89 points by kornish 6y ago

I first learned about ADRs in a course led by Michael Nygard, author of the book Release It (https://pragprog.com/titles/mnee2/release-it-second-edition/ https://pragprog.com/titles/mnee2/release-it-second-edition/). Since then, I've seen them used well by our Platform Team (Scaling/SRE/Infra), but our product teams have not adopted. Interesting to also read Nygard's post from 2011 on ADRs: https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions https://www.cognitect.com/blog/2011/11/15/documenting-archit...

sdfhbdf 6y ago

There is a nice discussion around a GitHub blog post about them from 6 months ago: https://news.ycombinator.com/item?id=24146594 https://news.ycombinator.com/item?id=24146594 This could give some context to people hearing about ADRs for the first time

GordonS 6y ago

Anyone know of any OSS projects that are using ADRs? I'd love to see some examples of them being used in the wild.

_nhynes 6y ago
https://github.com/oasisprotocol/oasis-core/tree/master/docs/adr https://github.com/oasisprotocol/oasis-core/tree/master/docs... This one was my first exposure to ADRs. I liked how they went with something standard instead of doing the blockchain traditional X Improvement Proposal (BIP, EIP).
jph 6y ago
Yes this open source repo: https://github.com/joelparkerhenderson/architecture_decision_record https://github.com/joelparkerhenderson/architecture_decision... See the `examples` directory for real ADRs, such as for CSS frameworks (e.g. Bulma), secrets storage (e.g. Bitwarden, Vault), programming language stack (e.g. Typescript, Rust), etc.
draklor40 6y ago
https://github.com/backstage/backstage https://github.com/backstage/backstage Makes it easy to understand the reasoning behind a lot of decisions.
- doctor_eval 6y ago
  I haven’t seen backstage before and it looks awesome. Thanks!

ryeguy 6y ago

How do RFCs and ADRs play together? Would you consider a finalized RFC (all comments/concerns addressed in some way) to be an ADR?

vaughandroid 6y ago
We use at both in my department at work. They is some overlap, but since each have different strengths I think they work well together. RFCs are great for capturing discussions and exploring ideas in depth. You can get deep into the details if needed. ADRs are all about capturing a decision. They should capture the important bits of context and consequences, but without a huge amount of detail. In terms of the process for producing these documents, if a decision is straightforward we will go straight to writing an ADR. If there are multiple options or we want to explore some corner cases, we'll start with an RFC. An ADR is often part of he output of an RFC which reaches consensus, but not always. Related RFCs and ADRs include links to one another. If people are looking to get up to speed on something, their first port of call is the ADRs. If they have concerns, disagree with a past decision, or simply want to know more then they can dig into the RFCs.
deleted 6y ago
[deleted]

The_rationalist 6y ago

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.

vikingcaffiene 6y ago

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

GSGBen 6y ago

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.

dijit 6y ago

I tried using these multiple times (I even know a contributor to this endeavour) but I always struggled with what the scope should be. 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. 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). Has anyone found a good threshold for what should be a new ADR from an ops perspective.

GSGBen 6y ago
"Based on my experience in this area and with this business, will I likely be asked about this later and will I confidently and easily be able to answer? Is the expected value of recording higher than the expected value of not (factoring in time, noise, mental load later etc)?" is something like what I ask myself to help decide. Also if you make it filterable and searchable (table instead of document format) you can minimise the issues of having a lot of them. You can add your own scale/importance tags as well to give a list of overview ones to read through too.

ta988 6y ago

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.

flarg 6y ago
I use Python PEPs for architecture decision logs

baconforce 6y ago

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.