Why We Write Design Docs After the Prototype

The conventional wisdom gets it backward

Most engineering playbooks say the same thing: write a design doc, get sign-off, then build. The logic sounds airtight. Plan before you act. Think before you code.

But for a small team working under real constraints—limited time, limited people, limited patience for ceremony—that sequence produces a specific failure mode. You spend days writing a document full of hypothetical trade-offs. You debate edge cases that may never materialize. You spec an interface against assumptions that collapse the moment code hits a real environment. Then you build something different anyway and the doc becomes a fossil.

We tried it both ways. Writing the design doc after the prototype produces better documents and better systems.

Hypothetical trade-offs are the wrong trade-offs

A design doc written before any code exists is a work of imagination. That's not an insult—imagination matters. But the trade-offs you identify in a blank editor are rarely the trade-offs that actually govern the system.

Before building, you might spend a section debating two serialization formats. After building, you discover the real constraint is how a third-party dependency handles timeouts under load. The serialization choice was noise. The timeout behavior is the decision that shapes your architecture for the next two years.

Prototype-first documentation captures decisions forged under real physics. The doc records what you learned, not what you guessed.

What a post-prototype design doc actually contains

When we write a design doc after a working prototype, the structure shifts. Instead of "proposed approach," the doc describes the approach we chose and the ones we rejected—with evidence from the prototype about why.

A typical doc covers:

• The constraint that surprised us. Every prototype surfaces at least one wrong assumption. Naming it prevents the next team from repeating the exploration.
• The trade-off we accepted. Not a theoretical menu of options, but the specific compromise we made and what we gave up. This is the most valuable section. It tells a future reader what would break if they changed direction.
• The boundary we drew. Where the prototype's scope ends and why. What we deliberately did not build, and what signal would tell us to revisit that decision.
• The failure mode we tested. What happened when we fed bad input, pulled the plug, or doubled the load. Prototypes are cheap places to discover these things. Docs are the right place to record them.

This kind of document is shorter than a speculative design doc. It's also more honest.

Speed doesn't suffer—it improves

The obvious objection: "If you prototype first, you'll build the wrong thing and waste time." In practice, the opposite happens.

A prototype is not a production system. It's a fast, disposable exploration. Build it in a day or two. Cut corners deliberately. The goal is to make the important decisions visible, not to ship something.

The design doc you write afterward takes less time too, because you're not guessing. You're reporting. Drafting from lived experience is faster than drafting from speculation, because you don't get stuck in "but what if" loops.

Total calendar time—prototype plus doc—is usually shorter than a thorough pre-build design doc plus the rework cycle that follows when the plan meets reality.

The doc becomes a trust artifact

There's a second-order benefit we didn't expect. Post-prototype design docs earn more trust from the rest of the team.

When someone reads a doc that says "we considered three approaches and here's what we measured," they engage differently than when they read "we propose this approach and believe it will work." The first invites refinement. The second invites debate.

Review meetings get shorter. Comments focus on gaps in evidence rather than gaps in imagination. People trust the doc because it describes something that exists, not something that might.

When this doesn't work

This doesn't fit every situation. If you're building something with serious safety implications, or if the cost of a wrong prototype is high enough to matter, plan first. If coordination across many teams requires alignment before anyone writes code, a speculative doc might be the only way to move.

But for a small team building product infrastructure—where the biggest risk is spending a week on a plan that doesn't survive contact with reality—prototyping first and documenting second produces better artifacts and faster shipping.

The real purpose of a design doc

A design doc is not a permission slip. It's not a gate you pass through before you're allowed to build. Its real purpose is to make decisions durable—to help future engineers understand why the system looks the way it does.

That purpose is better served by a document written with real evidence in hand. Plan less, build a small thing, then write down what you learned. The document will be shorter, truer, and more useful than anything you could have written from a blank page.