Writing a 'why we chose X' post engineers can trust

Other engineers read a "why we chose X" post the way they read a sealed envelope: hoping it contains the answer to a decision they themselves have to make this quarter. Most of what is posted under that title is marketing in disguise — a victory lap with the hard parts quietly cut. The post that gets trusted, bookmarked and cited is the one that treats the reader like a peer sitting across the table: here is what we had, here is what we tried, here is what hurt, and here is what would change our mind.

This is how we would write one. The example throughout is a hypothetical decision about choosing a job queue for a small Python service; the shape works for any technology choice.

Start with the constraints that actually bound you

A decision looks arbitrary without its constraints. Features and benchmarks are comparable only after you say what was non-negotiable, and the honest list is usually short and unflattering: a deadline, a headcount, a budget, a skill the team already has or lacks, a system you cannot change. "We needed something that scaled" is not a constraint — every option scales to some degree, so it decides nothing. "We had six weeks before the release freeze, three engineers who already knew Python, and a relational database already in production" is a constraint, and already rules out half of the field.

Put this at the top of the post, in a short paragraph, as plain ordinary text. Include the constraints that are embarrassing to admit: a hiring freeze, a prior outage that scared the CTO, a product deadline that took precedence over anything elegant. Readers trust a decision when they can see the shape of the box it fits into.

Name the alternatives you actually considered

A useful alternatives list has three parts. First, the serious contenders: the two or three you spent real time with. Second, the ones you ruled out early, with one honest reason each — "nobody on the team had used it", "licence terms did not fit", "last commit was more than a year ago". Third, the one you did not evaluate at all and why: you heard about it too late, or you were specifically told not to.

Describe each contender the way its maintainers would describe it, not the way a competitor would. If you cannot steelman an option, you did not really consider it, and the reader can tell. Say what each one is good at, not only where it failed for you — many of your readers have different constraints, and your weakest alternative may be their strongest. The job of this section is not to justify your choice; it is to let readers see that you looked.

Say what you had to give up

Every choice costs something. If you cannot name what you traded away, you were comparing on taste. The honest list usually covers operating cost (new infrastructure to run, a new on-call rota), a new skill the team has to pick up, a feature you have now and will lose, and the lock-in you are accepting — the paths back out that just closed.

Write this section as a short paragraph per cost, not as a cheerful "trade-offs" table. Tables flatten severity. "We give up the ability to run the system entirely on our own hardware" is a different kind of cost from "learning a new query dialect"; tucked into the same row they look the same. Put the one that would most upset a careful reader first, so nobody can say later that they missed it.

Report the one or two measurements that actually decided it

Most "why we chose X" posts include a benchmark table. Most of those tables did not decide anything — they confirm a choice already made. The useful section is smaller and more honest: the one or two tests whose outcome would have flipped the decision. State the test, the inputs, the hardware and the result as hypothetical numbers rounded to the precision you actually trust.

For our queue example, the deciding measurement was tail latency for an enqueue-then-dequeue round trip at a hypothetical peak of roughly 400 jobs per second on the staging instance; everything else — throughput, memory use, dashboard quality — sat within a range we could live with. Say so. Then list what you did not measure and why: failure modes under network partitions, behaviour at ten times today's load, cost at scale. A reader whose workload lives in one of those blind spots now knows to look elsewhere.

Say what would make you reconsider

The signal of a trustworthy decision post is a concrete reopening clause. Not "we will revisit in six months" — calendar-based reviews are performative — but a specific condition under which the decision no longer holds. Our queue choice would come up again if the sustained ingest rate crosses roughly five times today's, if the team drops below two engineers who can maintain it, or if the upstream project changes its open-source licence.

Write the triggers in the present tense so a future reader can check them against their own numbers. Phrase them so that someone outside your team can tell whether the condition is already met. "If we outgrow it" is not a trigger; "if the daily job count stays above two million for four weeks" is. The publishing guidelines ask authors to flag claims that could age poorly — a reconsideration clause is how you flag your own.

Make the post you can keep honest

A decision post is a living document. A year on, one of the alternatives will have shipped a feature that changes your reasoning, your constraints will have shifted, or your "would reconsider" trigger will have fired. Build the post so you can update it without breaking the contract with earlier readers. We keep the file next to a short header, versioned in the repository:

---
title: Why we chose X for the job queue
status: accepted
decided: 2026-07-14
tested: staging-2 (8 vCPU, 16 GB RAM) on 2026-07-10
reconsider-if:
  - sustained ingest > ~5x current for 4+ weeks
  - fewer than 2 engineers who can maintain it
  - upstream relicenses away from open source
alternatives: [Y, Z, keep-building-on-cron]
---

Link the header from the post, and when you revise, follow our rules for updating a technical post without breaking trust: put the change at the top in a dated note, keep the old reasoning below struck through, and say whether the decision itself has changed or only its context. If the decision does flip and readers need to move off the choice they made on your advice, that becomes its own post — a migration guide with tested steps, a backup check, and a tested way back.