Your Spec Is Not Done When You Publish It

Most PMs treat a spec like a press release. You write it before the work starts, you publish it, and then it exists. Somewhere. Whether anyone reads it — or whether it’s still accurate by week three — is a separate, rarely examined question.

This is the wrong mental model. A document isn’t a deliverable. It’s infrastructure. And like all infrastructure, it needs maintenance.

The moment a spec becomes a liability

A spec becomes a liability the moment the plan changes and the document doesn’t. This happens constantly. Engineering discovers a constraint. A stakeholder changes their mind about a priority. A dependency shifts. The canvas changes; the document doesn’t. Now you have two sources of truth — except one of them is wrong, and nobody knows which.

The typical response is to stop trusting documents altogether. Which is a reasonable response to an unreliable system, but a terrible outcome. The team loses the shared reasoning that the spec was supposed to provide, and decisions start living in Slack threads and people’s heads.

Drafts as a forcing function

One thing that helps: separating writing from publishing.

When a document has a draft state, your edits are private until you decide they’re ready. You can revise the scope mid-sprint without confusing everyone who’s already read the current version. You can sketch out a change, share it with one teammate for a quick sanity check, and then publish it once it’s solid.

The draft also forces a conscious act of publishing — a moment where you decide “this is what we’re doing now.” That moment matters. It creates a clear signal for the team that the spec has changed, rather than the silent drift that happens when documents get edited in place without notice.

Comments on the passage, not just the document

Another failure mode: feedback lives somewhere else.

Someone reads your spec, has a question about a specific sentence, and pings you on Slack. You answer. The question and answer are now in Slack, divorced from the passage they referred to. Six weeks later, when a new engineer has the same question, they read the spec, get confused, and ask again.

When feedback is attached to the passage itself — as a highlighted comment right on the text — it stays there. The question is next to the sentence it refers to. Future readers see the annotation. The reasoning accumulates in the document instead of evaporating in a chat history.

Version history as a decision log

The other thing that accumulates: the decisions themselves.

Every time you publish a revision, that version is saved. In six months, when someone asks “wait, why did we cut the export feature from v1?” — the answer is in the version history. Not in a Slack search. Not in someone’s memory. In the document, where it belongs.

This turns version history from a recovery tool into a planning artifact. The document becomes a record of how the thinking evolved, not just what the thinking is right now.

What “living document” actually means

Teams say “this is a living document” as a disclaimer. A hedge against the document being wrong. What they mean is: don’t hold us to this.

What it should mean is: we will keep this current, and here’s how you know when it changed.

The difference is maintenance. A document that gets draft revisions, comments on specific passages, and a version trail of decisions is actually living. A document with a disclaimer is just a document someone hasn’t deleted yet.

The spec isn’t done when you publish it. It’s done when the work is done — and by then, it should look different from the version you wrote at the start.