jargon

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

  1. 01

    someone asked whether this needed a written decision, and the answer was whether it would be expensive to change later.

    Architectural significance

  2. 02

    you asked why the queue was chosen and someone found a one-page file in the repository from 2023.

    Architecture decision record

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

  4. 04

    you presented the design and spent forty minutes on a question you had not thought to ask yourself.

    Design review

  5. 05

    before starting, everyone wrote down why this will have failed in six months, and two of the reasons were the same.

    Pre-mortem

  6. 06

    you spent two days finding out whether the library could do it at all, and threw the code away.

    Spike

  7. 07

    you demoed the working prototype and someone asked when it could go live, which was never the plan.

    Proof of concept

  8. 08

    you costed six weeks to build it and nobody costed the years of owning it afterwards.

    Build versus buy

  9. 09

    the third team this year proposed the same database and nobody could say whether it was already rejected.

    Technology radar

  10. 10

    you left the storage choice open until the access patterns were real, and then it was obvious.

    Last responsible moment

  11. 11

    the meeting spent five minutes on the data retention policy and thirty-five on the button label.

    Bikeshedding

  12. 12

    the room had agreed until the director said what they preferred, and then everyone had a new opinion.

    HiPPO

  13. 13

    you argued hard against it, lost, and then did the work properly instead of relitigating in every standup.

    Disagree and commit

  14. 14

    you argued a position firmly, someone produced a number, and you changed your mind in the same meeting.

    Strong opinions, weakly held

  15. 15

    two teams had been stuck for three weeks and it took one meeting with someone who owned both.

    Escalation