How to Write a Design Doc Alternatives Section in English

The alternatives section is often the most-read part of a design doc during review, because it shows reviewers you actually considered other approaches instead of jumping straight to your preferred solution. Writing it well in English requires vocabulary for comparing options fairly — describing why an approach was rejected without dismissing it unfairly or making the writer look like they didn’t seriously consider it. This guide covers how to structure and phrase that section.

Key Vocabulary

Alternative considered — a heading or label introducing an approach that was evaluated but not chosen, signaling to the reader that the comparison was deliberate. “Alternative considered: using a message queue instead of direct synchronous calls between services.”

Trade-off — a way of framing a rejected option’s downside not as a flaw, but as a cost that was weighed against a benefit, keeping the comparison fair and specific. “The trade-off with the queue-based approach was added operational complexity in exchange for better fault isolation — we judged the complexity wasn’t justified at our current scale.”

Rejected because — a direct, specific phrase for stating why an alternative wasn’t chosen, which should always be followed by a concrete reason, not a vague dismissal. “Rejected because it would require a schema migration on a table with over 200 million rows, which our current tooling can’t do without extended downtime.”

Not pursued further — softer language for an alternative that was briefly considered but not deeply evaluated, useful when you want to acknowledge an option without implying a full analysis was done. “A fully event-sourced architecture was considered but not pursued further, given the scope and timeline of this project.”

Revisit if — a forward-looking phrase noting the conditions under which a rejected alternative might become the right choice later, which shows the decision isn’t treated as permanently closed. “We’d revisit the queue-based approach if write volume grows beyond roughly 10x current levels.”

Common Phrases

• “Alternative considered: [approach]. Rejected because [specific, concrete reason].”
• “This approach would have solved [problem], but at the cost of [trade-off].”
• “We chose not to pursue this further, given [constraint — time, scope, team expertise].”
• “This remains a reasonable option and we’d revisit it if [condition changes].”
• “For completeness, we also considered [approach], though it was ruled out early due to [reason].”

Example Sentences

Introducing an alternatives section: “Before settling on the synchronous API approach described above, we evaluated two other designs. Each is described below along with the reasoning for not selecting it.”

Describing a rejected alternative fairly: “Alternative considered: a fully asynchronous, event-driven architecture using a message queue. This would have provided better decoupling between services and improved resilience to downstream outages. We rejected it for this project because our current traffic volume doesn’t justify the added operational overhead of running and monitoring a queue, and the team doesn’t yet have deep operational experience with one. We’d revisit this if traffic grows significantly or if we adopt a queue elsewhere in the stack first.”

Acknowledging an option without deep analysis: “We also briefly considered building this as a third-party plugin rather than a core feature, but did not pursue this further given the tight timeline — it’s worth a proper evaluation in a future iteration.”

Professional Tips

• Never write “rejected because it was worse” — always name the specific trade-off or constraint driving the decision, so a future reader (including your future self) understands the actual reasoning.
• Use “revisit if [condition]” to keep the door open on rejected options — it signals intellectual honesty and prevents the doc from reading as defensive.
• Give genuinely considered alternatives roughly equal descriptive detail to your chosen approach — a one-line dismissal next to three paragraphs praising your own idea reads as biased, even unintentionally.
• Reserve “not pursued further” for options you didn’t fully evaluate — using “rejected because” for something you only briefly considered overstates your analysis.

Practice Exercise

1. Write an alternatives-considered entry for a design decision from your own work, including a concrete rejection reason.
2. Rewrite this weak rejection reason with something more specific: “We didn’t choose this option because it seemed too complicated.”
3. Draft one sentence using “revisit if” for an alternative you’re setting aside for now but not permanently ruling out.