The standard objection to writing the design down is that it is what you give up in exchange for speed. Early-stage companies are meant to be the place where you skip it: no specifications, no plans, just build the thing and find out. Documentation is treated as a tax that mature organisations can afford and small ones cannot.
I have worked the other way round, and I want to make the argument properly rather than just assert it.
At Cendra, across a twelve-month tenure as one of two founding engineers, the work produced 255 design specifications, 207 implementation plans and 17 production runbooks. Over the same period: 377 production releases coordinated across four repositories, and 482 merge commits across those repositories (an all-merges count, broader than the frontend-only first-parent integration figure on the Cendra page), across 239 active development days. That release figure works out at roughly one every twenty-two hours.
All of those figures are tenure-scoped, and self-measured against private repositories while I held authorised access to them, which is a caveat I will come back to. But the shape is the point: the documents and the shipping happened together, at the same time, by the same person.
What I am not claiming
I cannot prove the specifications caused the cadence. There is no control group. It is entirely possible to imagine a version of that year with no documents and more releases, and I have no way to rule it out.
What I can do is describe precisely what the artefacts removed from the critical path, and let you judge whether that is worth the hours. The mechanism matters more than the correlation, because the mechanism is the part that transfers to your codebase rather than mine.
The specification is a comprehension test I administer to myself
The honest reason I write a design down before building it is not communication. It is that writing it is how I find out whether I actually understand the problem.
There is a specific and reliable experience involved. Somewhere in the second half of a document, I reach a paragraph I cannot write. Not because the words are hard — because the thing I am trying to describe does not resolve. What happens when both of those conditions are true at once? Which side owns this state? What does the system do when the third case arrives, the one I have been mentally filing as "unlikely"?
That paragraph is the design flaw, and it has surfaced while it costs a paragraph. The same flaw surfaces on its own eventually. It just surfaces after the schema is written, after two features depend on the shape, after something is in production carrying data. The distance between those two moments is most of what people mean by "this took longer than we thought".
So the cheapest place for a design to be wrong is in a document, and the second cheapest is nowhere near as cheap. That is the entire argument, and everything below is bookkeeping on top of it.
Three artefacts because they answer three different questions
The counts differ — 255, 207, 17 — because the three documents do different work and are needed at different rates.
A specification says what a thing should do and why, including what it deliberately will not do. That last part earns its place more often than the rest. A written non-goal is the only defence against a feature that grows a third of the way through implementation, because "we said explicitly that this was out of scope" is a settled question and "I don't think we should do that" is a conversation.
An implementation plan says in what order, what can break, and what has to land before what. It exists because a design being correct says nothing about a sequence being safe.
A runbook says how the thing reaches production and how it comes back out. There are only seventeen because a runbook describes a recurring operation rather than a change: staged rollout, feature-flagged release, a forty-eight-hour post-merge soak, rollback procedures, cross-repository dependency ordering, smoke matrices, incident response and on-call handover.
The runbooks were the ones I nearly did not write, and they turned out to be the ones with the clearest payback.
The runbook exists because of a single point of failure that looked like competence
Releases spanned four repositories with real ordering constraints. Backend routes had to land before the frontend that called them. A web deployment and a mobile over-the-air bundle had to activate together, or a native shell would spend an afternoon calling an endpoint that did not exist yet.
That ordering lived in my head, and I was good at it. Which is exactly the problem: an engineer who reliably gets a complex sequence right is indistinguishable from a documented process until the day they are ill, on a flight, or gone. Being the person who knows the release order is not a strength. It is a single point of failure wearing a strength's clothes, and the fact that it feels good is what stops people fixing it.
Writing it down was the fix. It also made the sequence reviewable, which is a second-order benefit I did not anticipate: an ordering constraint you can read is one somebody else can find a hole in.
Where the speed actually comes from
Nobody's bottleneck is typing. The expensive things in shipping software are rework and coordination, and specifications attack both.
Rework, because a design flaw found in a document is fixed by editing the document. Coordination, because a written interface is how two people build against each other without a meeting. That second one was concrete for me: our AI engineer owned the LangGraph services, the agent workflows and the RAG pipelines, and I built the product layer those capabilities were surfaced through — agent configuration, the knowledge base, the agentic rule-authoring interface, the in-product assistant — plus the transport between them. I did not architect the orchestration underneath, and the boundary between us is exactly where a specification pays for itself. Two people can build towards a written interface concurrently. They cannot build towards a remembered one.
The third piece is a completion standard rather than a document. Nothing counted as done until I had watched it behave correctly in production logs, in the database, or on a real device. I adopted that after being wrong often enough to stop trusting a passing build — and the clearest illustration I have is a mobile feature that passed everything and still had to be removed after I reproduced its behaviour on a physical handset. Specify, implement, verify in production. The third step is where the specification either turns out to have been true or does not.
What the artefacts turned out to be good for that I did not intend
They are the only part of that work I can still point at.
Every repository I have shipped production code into belongs to somebody else, so demonstrating ownership becomes a problem of publishing a method rather than an artefact. Commit shares and blame analysis are self-measured; you are taking my word for the numbers and judging the method. Process artefacts sit differently. They existed in the repositories independently of my description of them, and two co-founders who were there have agreed to act as references and can confirm scope and ownership without me in the room.
I did not write 255 documents in order to have evidence. But a habit that produces its own record turns out to be worth more than a habit that produces only working software, when the working software is behind an NDA.
The same discipline runs in my own projects, at a scale suited to them: the autonomous documentary pipeline carries 25 design specifications committed alongside the code, including a build-versus-buy roadmap with licence analysis per component.
Where I would not write one, and what the counts do not tell you
A specification for a change whose blast radius is smaller than the document is ceremony, and ceremony is what gives specifications their bad reputation. My rule of thumb is to write one when the decision is expensive to reverse, when it crosses a boundary someone else builds against, or when the state it introduces will outlive my memory of why. A copy change, a dependency bump and a contained bug fix meet none of those.
And the counts are counts of artefacts, not of quality. 255 documents is not 255 good documents, and I would rather say so than present a number as evidence of uniform rigour. The only claim a count of this kind can support is that the habit was consistent. Nor is the order always clean: sometimes the honest way to understand a problem is to build a throwaway first and write down what I learned afterwards, and a document produced that way is still worth having even though it arrived out of sequence.
There is one more thing this discipline is quietly load-bearing for. LLM coding tools are central to how I work, and the specification is what makes that safe rather than fast-and-hopeful: it is the artefact a tool's output can be checked against, something outside my own memory of what I asked for. Working this way is what lets one engineer cover a large surface. The specs, the tests and the production verification are not decoration around that — they are the reason it holds.
Ownership evidence and how each figure was measured: Cendra.
This essay first appeared on my site — efe-genc-portfolio.vercel.app/writing/the-spec-is-the-fast-path/ — where every figure I quote carries its scope and how it was measured. If you have approached this differently, I would genuinely like to hear how; disagreement is the most useful comment I can get.
This article was originally published by DEV Community and written by Efe Genç.
Read original article on DEV Community