Confluence, Notion, Docs: Where Should a PRD Live?

The tool is not the bottleneck. A weak spec in Notion is a weak spec, and no amount of database views fixes a missing error state.

But the tool is not neutral either. Each one makes a particular failure easy and a particular discipline hard, and knowing which one you are exposed to is more useful than knowing which tool other teams prefer.

What a spec needs from its home

Six properties, independent of vendor:

Findable by the question, not the title. People arrive with "can admins export this?", not with the name you gave the page in March. Search has to work on the body.

Linkable at the section level. A requirement you can point at — in a ticket, a review, a message — is a requirement people cite. One you can only link as a whole document gets paraphrased instead, and paraphrase drifts.

Comments that survive. A resolved comment thread is a decision record. If resolving hides it permanently, you have deleted the reasoning behind a change.

Visible version history. Not for audit. So that "when did this become 20?" is answerable in ten seconds.

Reachable from where the work happens. If reading the spec requires leaving the tool the build lives in, it will not be read during the build.

Readable without asking. Permissions that require a request are permissions that produce guesses.

How each one fails

The honest comparison is not features. It is which failure each tool makes easy.

Tool	Genuinely good at	The failure it makes easy
Confluence	Hierarchy, search, permissions, an obvious home	Pages from 2019 that nobody archived and search still surfaces
Notion	Structure, databases, relations, fast linking	An elegant schema that nobody fills in after month two
Google Docs	Commenting, real-time collaboration, zero friction	A document that exists only in one person's Recent list
Repo markdown	Free version history, next to the code, changes get reviewed	Design, support and leadership never open it
Jira / Linear	Adjacent to the work, impossible to miss	The decision disappears when the ticket closes

None of those failures is a product defect. Each is the shadow of the thing the tool is good at — Confluence's durability is why stale pages persist, Notion's flexibility is why schemas outgrow their maintenance, the repo's rigour is why non-engineers stay out.

The rule that matters more than the tool

One canonical location per document, linked from everywhere else.

Almost every real documentation problem is duplication rather than tool choice. The spec in Confluence, a copy pasted into the ticket, a summary in Slack, and an older version in someone's Drive. Four artifacts, three of them wrong, and no way to tell which is which from the outside.

The discipline is boring and it is most of the value: the document has one home, everything else links to it, and nobody ever pastes the content somewhere a reader might find first.

The stale-page problem is a search problem

Worth separating from general clutter, because the mechanism is specific and the fix is different.

An out-of-date spec sitting in an archive harms nobody. An out-of-date spec that ranks above the current one in search is actively dangerous — somebody reads it, believes it, and builds or answers a customer against it. Nothing in the document announces that it was superseded eight months ago.

Two cheap habits handle almost all of this:

Date and status in the title or at the top. Not in a properties panel nobody expands. Visible in the first line, so a reader who arrived from search knows within two seconds whether they are in the right place.

Superseded pages link forward. One line at the top: "Superseded by [current spec]." This costs ten seconds at the moment of archiving and is the only thing that reliably stops a stale page from misleading someone, because it works even when search surfaces the wrong result.

Nobody owns the documentation system

This is usually the real answer to "why are our docs bad," and it is not a tooling answer.

Every team has an owner for the roadmap, an owner for the backlog, an owner for the release process. Almost none has an owner for the place the specs live. So the archiving does not happen, the duplicate copies accumulate, the structure drifts, and the eventual conclusion is that the tool is wrong.

The fix is unglamorous: one named person, fifteen minutes a quarter, with the authority to archive things other people wrote. That last clause is the part that gets negotiated away, and it is the part that makes it work.

A second reader has appeared

Worth noting because it changes the calculus slightly. Specs are now read by tooling as well as people — AI assistants pulling context, agents working in the repo, review tools.

That reader cares about a narrower set of the six properties: whether the document is reachable programmatically, whether it is text rather than an embedded diagram, and whether the current version is distinguishable from the old one. A spec locked behind a permissions wall or expressed mainly as images is invisible to it.

This is not an argument for moving everything into the repo. It is an argument for the same thing as before — one canonical, text-first, reachable copy — with one more reason attached.

Specs and decisions want different homes

Worth separating, because the retention needs differ.

A spec describes the current intent of a piece of work. It has a lifecycle — written, reviewed, built, done — and after that it is mostly historical.

A decision record outlives the work entirely. It answers "why is it this way" in eighteen months, long after the spec has stopped being read.

Putting both in the same place is fine. Assuming the spec will serve the second purpose is not: specs get superseded and archived, and the reasoning goes with them. That is why the log is append-only and lives separately even when it sits in the same tool.

The migration trap

Every two years somebody proposes moving. The pitch is that the current tool is why the docs are bad.

It is worth being clear-eyed about what migration actually does. You carry the same habits into a cleaner interface, and you usually lose comment history, link integrity and version history in transit — which are three of the six properties that mattered.

The honest test before agreeing to a migration: name the specific property the current tool cannot provide. If the answer is one of the six above, migrate. If the answer is "it feels cluttered," the problem is that nobody archives, and archiving is free in the tool you already have.

What actually correlates with specs that stay useful

Not the tool. Three habits, all portable:

Someone archives. A quarterly pass that moves finished specs out of the default view. Fifteen minutes, and it is the single highest-value maintenance act in any documentation system.

Amendments land in the document. When a decision changes mid-build, three lines go back into the spec the same day — rather than into the thread where it was decided.

Links point at the canonical copy. No pasting. Ever. The discipline sounds pedantic until you have watched two teams build against different versions of the same paragraph.

Do those three and the tool becomes close to irrelevant. Skip them and the best tool in the category will hold your stale specs in a beautiful hierarchy.

FAQ

Where should a PRD live? Anywhere that is findable by question, section-linkable, keeps comments, shows history, sits near the work, and does not require a permissions request.

Confluence or Notion? They fail differently — stale pages versus unmaintained schemas. Pick the failure you can manage.

In the repo? Good when engineering is the audience, bad when design, support or leadership need to read it.

Will migrating fix it? Almost never. You carry the habits and lose the history.