The design doc is a decision, not a description

Why the alternatives section is the one that makes a doc reviewable — and what happens when you score real options against the success criteria you already wrote.

You sent the assumption on Tuesday. Friday came and went, and nobody replied.

That is not the technique failing — that is the technique working. You have a stated default, a written record of when you asked, and you are not blocked. You are building generic SAML, the larger of the two scopes, exactly as you said you would. Now you have to propose how.

What the design doc is actually for

The glossary defines a design doc as how a chosen solution will be built, assuming the problem is already agreed. That is accurate and it is also where most people go wrong, because “how it will be built” sounds like a description — and a description is not reviewable.

Think about what a reviewer can do with a document that says only here is what I am going to build. They can agree, or they can object and look obstructive. There is no third move. Now give the same reviewer a document that says here were the three options, here is what each one costs, here is the one I picked and here is what it gives up. Suddenly they can engage with the reasoning: challenge a cost estimate, add a fourth option, or accept the tradeoff explicitly.

This is why Google’s own guidance treats Alternatives considered as one of the most important sections in the document rather than an appendix (Malte Ubl, “Design Docs at Google”). It is the section that demonstrates the selected solution is the best one given the stated goals — which only works if the goals were stated somewhere first. You wrote them in lesson one.

Three real options for enterprise SSO

Enough abstraction. Here are the actual choices in front of you, with real numbers.

Option A — Buy a hosted provider

Vendors like WorkOS sit between you and the customer’s identity provider, giving you one integration that covers Okta, Microsoft Entra, Google Workspace and dozens more. WorkOS publishes SSO at $125 per connection for the first fifteen, with volume pricing above that (WorkOS pricing). The shape that matters more than the figure: cost scales with the number of enterprise customers you land, which is also the number you are charging. Auth0 prices on a different axis — per monthly active user, with enterprise SSO on higher tiers — which behaves very differently at your size.

Quote the published tier, not a number from a comparison article. When you put a vendor’s price in a design doc, link the pricing page and say which tier you assumed, because someone will check and the tiers move.

Option B — Build it on a SAML library

Implement SAML yourself against an open-source library. No per-customer fee, complete control of the flow, and you own every hour of it: the initial build, the per-customer configuration support, and the security surface of an authentication path you now maintain. Worth knowing that Okta, Entra and Google Workspace account for something over 80% of enterprise SSO connections, so “generic SAML” is a bounded target rather than an infinite one — you are not writing an integration per customer.

Option C — SAML with just-in-time provisioning

The cheap, fast one. Accept the SAML assertion, and if no account exists for that user, create it on the spot at first login. No separate provisioning system to build, no vendor bill. This is the option that will be most tempting in the room, because it is the one that ships soonest.

Now score them against the doc you already wrote

An options table is decoration unless you evaluate it against something. The something is the success criteria from your one-pager. Here is the criterion from lesson one:

Enterprise customers can provision and deprovision users via their identity provider with zero manual account creation by our team.

Two protocols are hiding in that sentence, and they are not the same one. SAML authenticates — it proves who someone is at the moment they log in. SCIM provisions — it is a separate protocol the identity provider uses to tell your system that an account should exist, or should stop existing (Clerk, “Federated identity for enterprise SaaS”). Enterprise security questionnaires ask about them separately, and “do you support SCIM?” is a standard line item.

Which kills Option C outright. Just-in-time provisioning is create-only. It fires when a user logs in, so by construction it has no mechanism for the case where a user stops logging in — an employee who leaves keeps their account indefinitely (PropelAuth on SCIM provisioning). Option C satisfies “provision” and cannot satisfy “deprovision”, and deprovisioning is the half enterprise buyers actually audit.

Where people get burned

Every source above sells identity software. WorkOS concluding that buying beats building is not neutral analysis, and neither is a vendor’s page explaining why you need the protocol they implement. The protocol facts are checkable and hold up — SCIM really is separate from SAML, JIT really cannot deprovision. The recommendations are marketing. Cite the first, discount the second, and say in your doc which is which.

Retrieval check

Without scrolling up: what turned the options table from a list of preferences into a decision? Name the specific mechanism.

Check your answer

Scoring each option against the success criteria written in the one-pager. Option C was eliminated by a criterion the author had already committed to in writing, not by taste or seniority — which is what makes the elimination arguable on evidence rather than on authority. An options table with no criteria to score against is just a list of things someone thought of.

A recommendation that names its own cost

Two options survive, and neither is free. Buying gets you SAML and SCIM immediately and puts a per-customer line item on the P&L forever. Building costs engineering time now and ongoing maintenance of a security-critical path, in exchange for no marginal cost per deal.

The senior move is not picking the clever one. It is stating the recommendation together with the thing it gives up, in the same sentence, so nobody has to discover the downside later:

“Recommend Option A. It unblocks the $400K deal this quarter, which is the stated why-now, and it costs roughly $125 per customer per month forever — a cost that grows precisely as we succeed. I am proposing we accept that in exchange for the quarter, and revisit if we pass roughly 40 connections.”

A reviewer can argue with that. They can dispute the threshold, question whether the deal is really quarter-bound, or point out a fourth option. All of those are better conversations than the one that starts three months into a build.

Now apply it: write the options table

Hands on

Turn the three options into a decision

Done when: You have an options table scored against your own success criteria, and a one-sentence recommendation that names what it gives up.

Pull the success criteria section out of your lesson-one draft and put it at the top of a new page. No draft? Use the criterion quoted above — the provision-and-deprovision one.
Make a table: three rows for the options, and one column per success criterion, plus a column for cost. Fill in each cell with meets / fails / partly and a handful of words on why.
Mark any option that fails a criterion outright. Do not delete it — the rejected option is the evidence that you considered it, and deleting it is how docs end up looking inevitable.
Pick one of the survivors and write the recommendation as a single sentence containing three things: what you chose, which stated goal it serves, and what it costs you.
Add one line naming the condition under which you would revisit the decision. If you cannot name one, your recommendation is a belief rather than a tradeoff.
Bring the table and the recommendation into the chat. I’ll review it the way the staff engineer on your team would — pushing hardest on any cell where “partly” is doing work that a real answer should be doing.

What this does not cover

You have a decision and the reasoning behind it. What you do not have is anyone else’s agreement to it — and a decision document that has not survived other people is just a well-organised opinion. Circulating it, and reading what comes back, is where this goes next.