Weeknotes

Weeknotes for the week finishing Friday, 16 January 2026.

This week, I:

  • went to Oxford for the OpenPrescribing kick-off meeting
  • wrote two ADRs (Architectural Decision Records)
  • learned more about DuckDB
  • learned more about BNF codes
  • wrote issues
  • caught a cold

ADRs

I want to write a little about ADRs, because I spent a non-trivial amount of time this week thinking about what they are and why we should write them. You can find our definition and rationale in the codebase. I’m pleased that ADR-000 is self-exemplifying; in other words, the team’s decision to record architectural decisions is captured by an ADR.

If it’s not clear, then I’m an advocate for writing ADRs. Indeed, I’m such an advocate that I made the team an offer: When we make a decision, I will write the ADR. The team accepted, although I’m regretting that my offer didn’t have an expiry date.

What I’d like to focus on here is the questions software developers often ask about ADRs and the reasons they often give for not writing them. First, some questions.

  • What distinguishes architectural decisions from other decisions about a codebase?
  • How detailed should an ADR be?
  • How long should it take to write an ADR?
  • When should I write an ADR?
  • Is it okay to write an ADR retrospectively?
  • Is it okay to change an ADR, once it’s written?
  • Do the benefits really outweigh the costs?

And second, some reasons:

  • Information about code should live as close to the code as possible. ADRs are not close to the code.
  • Large organisations are advocates for writing ADRs, but that doesn’t mean that small organisations should write them, too. Small organisations and large organisations are different.
  • Like Amazon, one of our Leadership Principles is Bias for Action. ADRs hinder this leadership principle.

I could reword the questions as reasons (“It takes too long to write ADRs”), but you know that already.

Alas, I don’t have time to write more. But something is better than nothing.

I’d like to thank Lucy, Peter, and Suzanne for their questions and comments about ADRs last week and this week.