Write the 'Alternatives Considered' Section of a Design Doc So It Actually Justifies the Decision

I've picked an approach for a design doc and I'm now writing the 'Alternatives Considered' section. I want this section to do real work — let a future reader (including future me) understand why the chosen approach won, not just list other options as a formality before the doc moves on.

Here's what I have:
- The chosen approach: [DESCRIBE what you decided to build/do]
- The problem it solves: [DESCRIBE the constraint or requirement driving the decision]
- Other approaches I considered, in whatever rough shape: [LIST the alternatives, even informally — things you seriously weighed, things a reviewer is likely to ask 'why not just do X' about, and things you rejected quickly]

Help me turn this into a real 'Alternatives Considered' section by:
1. For each alternative, stating the strongest honest case for it — not a weakened strawman version that makes the chosen approach look obviously better. If an alternative was genuinely competitive, the writeup should make that visible.
2. Naming the specific reason each alternative was rejected in terms of an actual tradeoff (cost, latency, operational complexity, team familiarity, time-to-ship, a hard constraint it fails to meet) rather than a vague 'not as good a fit.'
3. Flagging any alternative that's likely to be the first thing a reviewer proposes in comments, so I make sure it's addressed head-on rather than omitted or buried.
4. Noting which alternatives were rejected primarily on incomplete information or a time-boxed decision, versus ones rejected because they're fundamentally the wrong shape for the problem — the doc should be honest about which is which, since a future team revisiting this decision needs to know if circumstances changing would flip the answer.
5. Keeping each alternative's writeup to a few sentences — this section should be scannable, not a second design doc for the path not taken.

Output the section in the actual format I'd paste into the doc, not a description of what it should contain.

Sign in to upvote this prompt.