Write down the choice while it is still fresh
Six months after a queue is introduced, someone will ask why a request cannot complete synchronously. The useful answer includes the timeout that caused trouble, the delivery guarantee the product needed, and the operational cost the team accepted. Meeting notes rarely put those facts together.
Create a decision record when a choice will constrain later work: an API contract, a database boundary, or a dependency that will be expensive to remove. Give it a stable filename and link it from the relevant issue or code. Write the first draft while people still remember the alternatives.
Use a concrete example
Suppose report generation is exceeding the request timeout. A useful record could say: 'Generate reports in a background worker. The request returns a job identifier; the client polls for completion. Retain finished downloads for the agreed period.' That tells another engineer what they must implement.
Then explain the consequence: the product needs pending and failed states, operations must monitor the worker, and the API needs a way to retrieve job status. The record is incomplete if it describes only the shorter request time.
- Context: which request times out, under what conditions, and what evidence demonstrates it.
- Options: synchronous generation with limits, precomputed reports, or a background job.
- Decision: the selected behavior and who accepted its costs.
- Review trigger: a changed report size, completion requirement, or operating constraint.
Compare the options against the actual constraint
If users need a report generated from current data, yesterday's precomputed file may fail the requirement regardless of its speed. If a report is small and predictable, a queue may add more work than it removes. Compare the options using those conditions before assigning scores to broad labels such as maintainability.
Separate measured facts from estimates. Link to the timeout trace. Label the expected queue volume as a forecast. If nobody knows whether the export can be streamed within the existing timeout, run that experiment and record the result.
Keep the objection that could matter later
Name who makes the decision and set a deadline for comments. A record left permanently proposed can be implemented anyway, leaving everyone unsure whether the choice was accepted.
Keep substantial objections in a sentence or two. 'Polling may create excessive traffic if customers generate many reports at once' is worth retaining, along with the chosen mitigation. It gives a future review something specific to check. There is no need to preserve every comment or attach names to every disagreement.
Link the replacement when the decision changes
When requirements change, write a new record and mark the previous one superseded. Keep the old explanation accessible from its original link. Someone investigating an older release may need to know why it behaved differently.
Review the record when its stated condition occurs or when code crosses the boundary it defines. If engineers repeatedly ask the same question after reading it, fix the missing explanation. The document earns its place by helping someone make the next change.