Architecture & practice·topic 4 of 10
Making and recording decisions
How a group of people who disagree arrive at one design and leave a trail explaining why. Most of the pain of joining a codebase is that these documents were never written, so the reasons are gone and only the consequences remain.
Read in order · tick what you already know
- 01
someone asked whether this needed a written decision, and the answer was whether it would be expensive to change later.
Architectural significance
- 02
you asked why the queue was chosen and someone found a one-page file in the repository from 2023.
Architecture decision record
- 03
you wrote up the plan and left it open for a week so people could argue in the margins before you built anything.
Request for comments
- 04
you presented the design and spent forty minutes on a question you had not thought to ask yourself.
Design review
- 05
before starting, everyone wrote down why this will have failed in six months, and two of the reasons were the same.
Pre-mortem
- 06
you spent two days finding out whether the library could do it at all, and threw the code away.
Spike
- 07
you demoed the working prototype and someone asked when it could go live, which was never the plan.
Proof of concept
- 08
you costed six weeks to build it and nobody costed the years of owning it afterwards.
Build versus buy
- 09
the third team this year proposed the same database and nobody could say whether it was already rejected.
Technology radar
- 10
you left the storage choice open until the access patterns were real, and then it was obvious.
Last responsible moment
- 11
the meeting spent five minutes on the data retention policy and thirty-five on the button label.
Bikeshedding
- 12
the room had agreed until the director said what they preferred, and then everyone had a new opinion.
HiPPO
- 13
you argued hard against it, lost, and then did the work properly instead of relitigating in every standup.
Disagree and commit
- 14
you argued a position firmly, someone produced a number, and you changed your mind in the same meeting.
Strong opinions, weakly held
- 15
two teams had been stuck for three weeks and it took one meeting with someone who owned both.
Escalation