Muhammed Senussi
Muhammed Senussi
  • Muhammed Senussi
ADRs Are for the Person Who Arrives in Two YearsSoftware Architecture

Most teams that adopt ADRs write down what they chose and stop there. That is the least useful half.

Write the context like a witness statement

Record what was true at the time: the team size, the deadline, the thing you did not yet know, the option you rejected and why. A future reader who finds "we chose Kafka" learns nothing. One who finds "we chose Kafka because we expected replay to matter and we had one engineer who had run it" can check whether either of those still holds.

Keep them short, keep them in the repository, and never edit one after it is accepted. Supersede it with a new record instead — the trail of reversals is the most instructive document a codebase can have.

2 Comments

  • Peter Bakker

    April 30, 2024

    The "never edit after acceptance" rule is the one people resist and the one that makes the whole thing work.

    • Muhammed Senussi

      Muhammed Senussi

      AuthorApril 30, 2024

      Exactly. An edited ADR is just current documentation wearing a date. The value is that it captures what you believed then, including the parts that turned out wrong.

Leave a comment