Write Less About the Options You Rejected

Everyone agrees design docs should be short. Most of them aren’t. A few days into my new job at Shopify, a co-worker I’d known for less than a week, Jackson Marketon, gave me the best advice I’ve heard on fixing that: put the detail into the recommended option and the options still open, and keep the obviously wrong and rejected options brief.

Why design docs get long

Design docs tend to follow a familiar template: context, goals, options considered, recommendation. The “options considered” section is where the length comes from.

Writers give every option equal space. Partly that’s fairness, since giving each alternative a full hearing feels honest. Partly it’s defense. The author can hear a reviewer asking “did you consider X?” and writes three paragraphs on X so the answer is already on the page. The result is a doc where the option being recommended gets the same four paragraphs as the option nobody would ever pick.

The reader pays for that. They have to read the whole thing to work out which parts matter, and the parts that matter are buried among the parts that don’t.

Put the detail where the decision is

A design doc exists to help people make a decision, or agree with one. The reader needs depth in two places.

The first is the recommended option. This is what the team will build and live with. Spell out the tradeoffs, the failure modes, what it costs to run, how it rolls out, and how you’d back it out. If a reviewer is going to find a problem with the design, you want them to find it here, and they can only do that if the detail is in the doc.

The second is the open options: alternatives that are still in play, where reasonable people could land on either side. Give them enough detail to compare against the recommendation, and say what would settle the question. A benchmark, a conversation with the team that owns the downstream service, a cost estimate. An open option with no plan to close it is how one design review turns into three.

One sentence for the rejected options

The obviously wrong options still belong in the doc. Listing them answers “did you consider X?” before anyone asks, and it keeps someone from proposing X again six months from now. They don’t need a section each, though. A sentence each is enough, something like this:

## Rejected

- New standalone service: adds a deploy target and an on-call
  rotation for a feature with exactly one consumer.
- Cron job polling the table: ten-minute latency, and the
  requirement is under a minute.
- Vendor product: doesn't meet our data residency requirements.

Each line names the option and the one reason it lost. A reviewer who disagrees can ask, and the conversation starts from a specific reason instead of a wall of text.

This also works as a test. If a rejected option needs a paragraph to dismiss, it probably isn’t obviously wrong. Move it up to the open options and give it a real comparison. How long it takes to dismiss an option tells you how settled the question really is.

Architecture decision records already lean this way. Michael Nygard’s original ADR format has five parts: title, status, context, decision, and consequences. There’s no section for alternatives at all. The ones that matter show up in the context, briefly, as part of explaining why the decision was needed.

Spend the reader’s attention on purpose

Reviewers have a fixed amount of attention for any one doc. A doc that spreads it evenly across five options gets a shallow review of all five. A doc that concentrates its detail on the recommendation and the open questions gets a careful review of the parts that will become real code.

So sort the options before you write. Recommended, open, or rejected. The bucket decides how many words each one gets. The recommended option and the open ones get the paragraphs, and the rejected ones get a line.

A short doc gets read. A long doc gets skimmed, and a skimmed doc gets approved with its problems still inside it.

This advice has already changed how I write technical documents, and I plan to keep using it on every design doc I write from here on. Thanks, Jackson.