When the Source of Truth Isn't True

There’s a conversation that happens on almost every documentation project, and it goes roughly like this: you ask where the authoritative information lives. Someone points you to a Confluence page, a design spec, an internal wiki, a Notion doc, or — if you’re lucky — a GitHub repo. You go there, and what you find is six months out of date, internally contradictory, or missing the thing you most need to know.

The source of truth isn’t true.

The problem with “single source of truth”

The phrase itself is aspirational. A single source of truth sounds like a solved problem — one place, one version, one record. In practice, it describes an intention that erodes almost the moment it’s formed.

Systems change faster than documentation. Engineers fix behavior without updating the spec. Product makes a call in a standup that never makes it back to Confluence. Each of these is a small, reasonable thing. Collectively, they produce a source of truth that has drifted from what’s true.

What makes this particularly difficult for technical writers is that the drift is invisible from the outside. A Confluence page doesn’t announce that it’s stale. A spec doesn’t flag the three paragraphs that no longer describe the actual behavior. The document looks authoritative because it exists and no one has formally deprecated it.

So you either trust it and document something wrong, or you don’t trust it and spend time you don’t have verifying everything from scratch.

The alchemy part

Documentation is often described as translation — taking what engineers know and rendering it legible to the people who need to use it. That’s accurate, but it undersells the work. Translation assumes there’s a clear source to translate from.

The more honest description is alchemy: taking raw, impure inputs — partial specs, contradictory sources, half-documented systems, tribal knowledge locked in Slack threads — and transforming them into something that is accurate, useful, and durable enough to hold up when someone actually needs it.

That transformation is the job. It’s unglamorous and it doesn’t show up in the output. A reader looking at clean, accurate documentation has no visibility into the triangulation that produced it — the Slack thread you tracked down, the engineer who confirmed the spec was out of date, the three rounds of review that surfaced the edge case nobody had written down. The alchemy is invisible by design.

But it’s where most of the actual work happens.

What I’ve learned to do with bad source material

The first thing is to stop treating it as a documentation problem and start treating it as an information problem. A broken source of truth isn’t a failure of writing but a systemic one, usually accumulated slowly over a long time. Understanding that distinction changes what you do next.

Triangulate instead of trusting. When a source says one thing and the implementation does something else, that gap is information. It tells you that something changed and the record didn’t follow it. Your job is to figure out which is authoritative — the intent or the behavior — and document that, not split the difference.

Test the claims. For anything consequential, I try the thing myself before documenting it. API behavior, UI flows, configuration steps — if I can run it, I run it. This sounds obvious but it’s easy to skip when you’re under pressure. Skipping it is how wrong documentation ships.

Flag what you can’t confirm. When I can’t verify a specific claim, I flag it in review rather than paper over it. A technical writer who confidently documents something wrong is more dangerous than one who marks a section as needing verification.

Name the system problem, not just the gap. When the source of truth is broken, say so explicitly — to your team, to stakeholders — as a scope question, not a complaint. The current spec doesn’t match the implementation. Which should I document, and who can I work with to verify? That reframes it from something the writer silently fixes to something the organization owns. You didn’t create the drift. You shouldn’t be the only one resolving it.

Treat engineers as sources, not reviewers. The conventional model — writer drafts, engineer reviews — only works when you have a reliable source to write from. When you don’t, the instinct is to pull engineers in earlier. It rarely works either; they’re busy, and open-ended asks don’t get far. What works is doing the triangulation first, then coming with a specific question — not can you help me understand this, but here’s what I think is true based on the spec and the SDK. Am I reading this right? Engineers are usually willing to answer.

The documentation creates the truth

Here’s the uncomfortable corollary: when you write documentation for a system with a broken source of truth, you’re not just recording reality. You’re establishing it.

Accurate documentation for an underdocumented system becomes the reference everyone uses going forward. Engineers onboard against it. Support references it. New writers build on it. If you got it right, that’s good. If you made a reasonable call based on incomplete information and that call was wrong, the error becomes the record.

This is where the alchemy metaphor gets heavier. Alchemists were trying to produce gold from base materials. What you’re producing is institutional memory — documentation people will depend on long after you’ve moved on.

That’s worth taking seriously, even when the source material is a mess.