[HN Gopher] Architectural Decision Records (ADRs) (2018)
___________________________________________________________________
Architectural Decision Records (ADRs) (2018)
Author : kornish
Score : 66 points
Date : 2021-02-07 08:14 UTC (14 hours ago)
(HTM) web link (adr.github.io)
(TXT) w3m dump (adr.github.io)
| mountaineer wrote:
| 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/).
| 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-archit...
| vikingcaffiene wrote:
| 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 wrote:
| 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.
| sdfhbdf wrote:
| There is a nice discussion around a GitHub blog post about them
| from 6 months ago: https://news.ycombinator.com/item?id=24146594
|
| This could give some context to people hearing about ADRs for the
| first time
| ryeguy wrote:
| 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 wrote:
| 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]
| GordonS wrote:
| Anyone know of any OSS projects that are using ADRs?
|
| I'd love to see some examples of them being used in the wild.
| draklor40 wrote:
| https://github.com/backstage/backstage
|
| Makes it easy to understand the reasoning behind a lot of
| decisions.
| doctor_eval wrote:
| I haven't seen backstage before and it looks awesome. Thanks!
| jph wrote:
| Yes this open source repo:
|
| 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.
| _nhynes wrote:
| 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).
| The_rationalist wrote:
| 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.
| dijit wrote:
| 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.
| ta988 wrote:
| 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.
| baconforce wrote:
| 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.
___________________________________________________________________
(page generated 2021-02-07 23:01 UTC)