Six months ago the team spent two long meetings choosing a message queue. Today a new developer asks, in the planning meeting, why we did not just use the database for this. Two people who were in those meetings cannot quite remember the reasons. Forty minutes later, the decision is open again.
This is not really an argument about queues. It is a communication problem. The decision was made in a room, and the reasons stayed in that room. Once memories fade or people leave, a settled choice looks like an accident, and accidents invite questions.
A simple fix has been around for years. In 2011 Michael Nygard wrote a short blog post suggesting that teams record each significant architecture decision in a small text file, kept with the code. He called them architecture decision records, and many teams now just say ADRs.
Each record is short, often less than a page. A title. The context, meaning what situation you were in and what limited your options. The decision itself, written in plain words. The consequences, including the downsides you accepted on purpose. And a status, such as proposed, accepted, or superseded.
The consequences section matters most. We chose a separate queue, knowing it adds one more system to run, because we expected traffic to grow and wanted retries without locking tables. When someone later asks why not the database, the answer is already written, including the cost you agreed to pay.
Records like this do not stop people from questioning decisions. That is good, because some decisions should change. What they do is change the conversation. Instead of starting from zero, someone can say the context has changed, our traffic never grew, and propose a new record that supersedes the old one. The old one stays, marked as replaced, so the history is clear.
Start small. Next time your team makes a decision that took more than one meeting, offer to write it up in this format, and put it in the repository. Link to it in the meeting notes.
It takes about twenty minutes. The next time the question comes up, it may save the team forty.
– Asael Shinder
