Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Why Write ADRs

github.blog

Post reply on HN
Print view View original

51–60 of 64 posts

Re: Why Write ADRs

#51

Post by tsimionescu »

dgb23 wrote: post #39
rabidrat wrote: post #38

Earlier quoted context omitted.

> As soon you need to talk about these things over and over you want to write these down. This is the relevant part, to me. Can we do this documentation process JIT when someone asks about it? Maybe even convert the dialogue (in chat) or transcript of the conversation into the documentation.

I just started to write anything down basically... When a collaborator or client talks to me or when I think about something, then I open a markdown file (first often just a notes.md) and just write in bullet points, and gradually organize it into categories. I put these in version control as well since a while. Thought experiment: if something is not worth writing down, is it worth discussing?

> Thought experiment: if something is not worth writing down, is it worth discussing?

Writing things down in a way that can be consumed by others is usually significantly more work than discussing that same thing live (whether in text or verbally). As such, I would say that the answer is obviously yes.

Re: Why Write ADRs

#52

Post by zimpenfish »

vemv wrote: post #46

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 considerati…

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

But isn't that just an organic ADR?

Re: Why Write ADRs

#53

Post by willejs »

timwis wrote: post #50

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, se…

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!

Re: Why Write ADRs

#54

Post by pjmlp »

rabidrat wrote: post #38
dgb23 wrote: post #36

Earlier quoted context omitted.

I can only directly relate to solo/small-team projects: I find writing text (preference: Markdown) and sprinkling it with visualizations (tables, graphviz...) to document stuff very useful and productive. I don't see this as a burden but rather the opposite. A good portion of programming is not writing code, but thinking and communication. Using text as a direct output of this process helps in many areas. Mostly beca…

> As soon you need to talk about these things over and over you want to write these down. This is the relevant part, to me. Can we do this documentation process JIT when someone asks about it? Maybe even convert the dialogue (in chat) or transcript of the conversation into the documentation.

Not really because there isn't a JIT budget in most projects, and they usually only get allocated via escalations, some of which imply doing the work for free.

Re: Why Write ADRs

#55

Post by dfcowell »

aplummer wrote: post #9
rabidrat wrote: post #3

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…

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

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.

Re: Why Write ADRs

#56

Post by zimpenfish »

dglass wrote: post #26
linux2647 wrote: post #6

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.

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 wh…

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

Re: Why Write ADRs

#57

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

Re: Why Write ADRs

#58

Post by rham »

jsdalton wrote: post #42

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…

I recently rolled off a sweet FinTech project with a Fortune 500 bank’s Emerging Technologies team which has the best ADR implementation I’ve seen thus far.

Just fyi, these ADRs, written in Markdown, are kept in separate repo with special Markdownlint rules applied to ensure consistent formatting. But what made this team’s ADR implementation stand out to me were not the technical details of how they were maintained, but rather the SOPs they’d strictly adhered to.

In essence, they had a very academic perspective on ADRs, viewing them more like a potentially publishable white-paper- not necessarily in terms of length or formality, but procedurally. The rule we followed was that a spike should lead to an ADR, which made writing an ADR much more of a build-measure-learn cycle and kept quality high, since authors weren’t scrambling to remember their entire thought process after the fact. This also greatly improved the quality of the spikes themselves, as we spent less time falling down rabbit holes. Basically, a spike became strictly a determination of either feasibility or implementation, with an explicit record of that the determination and the way in which it was made, as well as the other trade-offs considered.

Re: Why Write ADRs

#60

Post by dllthomas »

vemv wrote: post #46

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 considerati…

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

Post reply on HN