Ask HN: How quickly should ADRs be implemented?

3 points

5 years ago

We use Markdown Architectural Decision Records (MADRs) to ensure that the product is moving in the right direction, from a high-level technical perspective (https://adr.github.io/madr/). This is really meant to capture only high-level technical decisions, like "use Grafana for producing dashboards" (as opposed to "it's okay to clone a ReactJS project that does the same"). Sometimes, these ADRs invalidate existing code, which means that implementation work needs to be done to bring the code in line with the ADR.

How quickly are such ADRs supposed to be implemented? I see two extremes:

- Implement them "just in time": When new code is written or old code needs to be changed anyway, developers need to take a decision. ADRs only influence these decisions. Pro: ADRs do not create extra "work" but still slowly steer the product in the right direction. Con: Devs might get confused about the state of an ADR. ("Why do we still have code that does X, when we have the ADR that says Y?") This also encourages a "broken window" argument to not implementing ADRs.

- Immediately: The ADR is immediately expanded in tasks that get high priority. Pro: ADRs move quickly from accepted to implemented, no cognitive load due to contradictions. Con: Sounds like what Joel advised not to do: https://www.joelonsoftware.com/2000/04/06/things-you-should-never-do-part-i/

Between these two extremes, I'm sure there are as many options as IT shops.

I'm not sure there is a right or wrong answer here. Also, what is right might depend on the project, the team, and the ADR itself. Rather, I'm looking for learning more on how others integrate ADRs into the development process.