Docs-Driven Development Is Half-Right

I used to write the README before the code. Every side project, every internal tool, every half-baked SaaS idea. The pitch was irresistible: if you cannot explain the feature clearly, you do not understand it yet, so stop typing code and start typing prose. It is the same instinct that makes docs as code appealing to engineers, the belief that documentation is not separate from the work, it is the work. After a few years of actually doing docs-driven development across a dozen projects, I think the advice is half-right. It works beautifully for one category of code and quietly sabotages another, and almost nobody distinguishes between the two before they adopt it.

Here is the distinction that matters. Docs-driven development works when the contract is the product. It fails when the contract is a guess. APIs, libraries, protocols, CLIs: contracts. The docs describe the shape of a thing other people will depend on, and getting that shape right before you commit to an implementation saves months of breaking-change pain downstream. Product features: guesses. You think users want a filtering UI, you write the doc, you build it, and two weeks after launch you learn they wanted a saved-view feature instead. The pristine spec you wrote on Monday is a lie by Friday.

Where docs-first genuinely wins

The canonical Documentation-Driven Development gist puts it crisply: if a feature is not documented, it does not exist. That framing makes sense for a library author. When I built a small auth SDK last year, writing the README first forced three decisions that would have been painful to unwind later. What does the default initialization look like. Does the token refresh function return a promise or a callback. Does the error object include the raw response. Those are shape decisions, and once real consumers depend on the shape, you cannot change it without a major version bump.

The README is a contract negotiation with your future users, conducted before any of them exist. That is incredibly valuable when the shape is load-bearing, like an API endpoint or a CLI flag that will ship in 10,000 automation scripts. You write the curl example, you feel it is awkward, you rename the parameter. Cost of change: a keystroke. After release, that same rename is a deprecation cycle, a migration guide, and a year of stale tutorials on Stack Overflow.

Ubuntu's engineering team wrote up a year of documentation-driven development in early 2026 and concluded exactly this: it works best when docs are an integral part of engineering, and especially when what you are documenting is how something gets used, not what it looks like internally. That is a specific claim. Not "docs improve quality." Interface docs improve interface quality, by giving you a cheap rehearsal of the commitment you are about to make.

Where it fails, loudly

Now take the same practice and apply it to a new product feature: a dashboard, a onboarding flow, a pricing page experiment. You write a doc that explains the feature, you get team sign-off, you build it. Three things go wrong, reliably.

First, the doc becomes load-bearing in a way it should not be. Product managers treat it as a spec, designers treat it as a brief, engineers treat it as a contract, and nobody has permission to change it without a meeting. You have invented a waterfall process and called it documentation. One of the best arguments for a tight documentation workflow is that it keeps docs in the room where decisions happen, not chained to a spec from two sprints ago.

Second, the doc is wrong within a week. The first time a real user touches the feature you learn that your "clear three-step flow" is actually a two-step flow with a modal. Now you have a choice: update the doc (extra work, nobody will thank you), or ship something different from what the doc says (the doc is now a lie). Teams almost always pick option three, which is to leave the doc alone and hope nobody reads it. That is how documentation rot starts.

Third, it conflates two different audiences. The internal spec your team needs to argue about the design is not the external doc your users need to understand the feature. Docs-driven evangelists write the user doc first, hoping it will double as the spec, and get neither. An internal Figma file, a Linear ticket, and a two-paragraph PRD do the spec job better. User docs get written when the feature is stable, not when it is a Jira ticket.

The honest counter-argument

The strongest defense of docs-first for product features comes from teams shipping with AI assistants. If you let a model read a detailed spec and produce the first draft of the code, the spec-as-prompt genuinely saves time. The spec is a compression of intent, the model decompresses it into a working implementation, and you iterate from there. Spec-driven development has exploded in the last year for exactly this reason, with search interest up more than 400% since last summer.

I will grant this. When the doc is actually a prompt, and the code is actually disposable, docs-first is a productivity multiplier. But notice what just happened. The doc is no longer documentation for users. It is a spec for a model. Calling that "docs-driven development" muddles two very different practices. One is about shipping a stable interface. The other is about steering an autoregressive code generator. They deserve different names and different rules.

What I actually do now

For library code, SDKs, CLIs, public APIs: README first, every time. I write the example I wish existed, I read it out loud, I rewrite it until it sounds obvious. Then I implement. The MVP documentation rule of thumb still holds, two pages and a reference, but the reference gets drafted before the code.

For product features: no docs until the feature is behind a feature flag with at least a few real users poking at it. The spec lives in a PRD and a Figma file. User docs get written when the flow stops changing weekly, which is usually a sprint or two after launch. An AI doc tool like the one we work on at Docsio can regenerate the user-facing docs from the shipped UI in minutes, so the cost of writing docs late has collapsed. The cost of writing them early and being wrong has not.

The pattern I wish more engineers used is not "write docs before code" or "write docs after code." It is "write docs at the point where cost-of-change crosses cost-of-staleness." For interface code, that point is before you implement. For product features, it is after the feature has survived contact with users. One rule, two very different answers.

If you are adopting docs-driven development this quarter, try it on your next CLI or your next public endpoint. Skip it on your next A/B test.