“We need a single source of truth.”
This phrase is said in thousands of product team meetings every year. It’s usually followed by a decision: we’ll put everything in Notion. Or Confluence. Or a shared Google Drive. Or this new wiki tool the VP of Product saw at a conference.
Six months later, the single source of truth has become one of twelve sources of partial truth, all of them slightly stale, none of them trusted.
This isn’t a failure of discipline. It’s a failure of design. And understanding why these systems fail is the first step to building something that actually works.
The Anatomy of a Decaying Knowledge Base
When teams set up a “single source of truth,” they usually create a documentation structure that looks coherent on day one: pages for each product area, sections for requirements, decisions, and rationale. It feels good. It’s organized.
Then the product starts moving.
A feature changes. Someone updates the ticket but not the doc. A design decision gets revised in a Figma comment but the spec isn’t touched. An engineer works around a constraint that was in the requirements but never told anyone the requirement was wrong. The PM gets pulled into a new initiative and stops maintaining the old ones.
Within weeks, different parts of the documentation are aging at different rates. Within months, the decay is total. The wiki has become an archaeological site — full of information, but none of it reliably current.
The fundamental problem: documents are static artifacts trying to represent a dynamic system.
Why Wikis Can’t Win
Traditional documentation tools have a structural weakness: they don’t know when they’re wrong.
A Notion page has no mechanism that says “this content was last verified against reality on date X, and the underlying system has changed Y times since then.” There’s no validity signal. The reader has no way to know if what they’re reading is current or three-year-old cruft.
The only available signal is the “last edited” timestamp — which tells you when someone last touched the document, not whether the product the document describes has changed.
This creates a rationality trap for teams. You can enforce documentation discipline — make it someone’s job to keep docs current — but this is expensive, error-prone, and fights against how teams actually work under pressure. Or you can accept that the docs will drift and absorb the cost of working from incomplete information.
Most teams do both: they enforce discipline aspirationally while absorbing the costs of drift practically.
What “Truth” Actually Means
To understand why semantic versioning helps, it’s worth being precise about what “truth” means in a product context.
A statement like “feature X works as described” is only meaningful at a specific point in time. Products evolve. What was true last quarter may not be true today. This isn’t a bug — it’s how product development works.
But most documentation systems treat their content as timeless. There’s no first-class concept of “this was true then, and here’s what’s true now.” The document either reflects current reality or it doesn’t, and there’s no formal way to express the difference.
Semantic versioning changes this. Every change to the product model is a versioned event. The history is the source of truth — not any snapshot of it. You can query the model at any point in time and get an accurate answer: this is what the product looked like at commit 147, on this date, approved by this person.
The “truth” is the sequence of changes. The current state is just the latest version.
How Structure Prevents Decay
The other reason traditional knowledge bases decay is that they’re unstructured. Prose is flexible, which makes it useful for communication — but it makes it impossible to validate automatically.
A paragraph that says “the checkout flow requires user authentication” is semantically meaningful to a human. But software can’t check whether it’s still consistent with the rest of your product model. There’s no way to programmatically detect when a downstream change has made that sentence wrong.
A structured product model is different. When “checkout flow requires user authentication” is expressed as a typed relationship between a Flow node and a Rule node, the system can enforce consistency. If someone removes the authentication requirement, the relationship is gone. Anything that depended on it is immediately visible as potentially inconsistent.
Structure enables automation. Automation prevents decay. This is the same reason typed codebases have fewer bugs than dynamically typed ones: the structure catches errors that humans would miss.
The Organizational Pattern That Actually Works
The teams that maintain reliable product knowledge long-term share a common pattern:
- The model is the artifact, not a document about it. The product graph is the source of truth. Docs are derived from it, not the other way around.
- Changes are made to the model first. When a product decision is made, it’s a structural update — not a prose edit that may or may not happen.
- History is preserved, not overwritten. Old product states are still accessible. Rollbacks add new commits rather than erasing the past.
- The model is queryable. Any team member can ask questions about the current state and get accurate answers, without needing to read everything.
This isn’t achievable with a wiki. It requires a system that treats product knowledge as data — structured, versioned, and machine-readable — rather than as prose to be curated.
The Payoff
When this works, the benefits compound over time. New team members can onboard by exploring the product model rather than reading stale documents. AI agents can query the product graph for context before generating code. Consistency checks can automatically surface conflicts before they reach development.
Most importantly, trust in the shared knowledge base is restored — because the model is always current by construction, not by manual effort.
That’s the real unlock. Not a better Notion structure. Not more documentation discipline. A fundamentally different kind of artifact — one that behaves less like a wiki and more like a semantic graph your whole team can query.