Your Documentation Is Lying to You: The Dangers of Out-of-Sync Content
The Most Expensive Typo in History
Space is hard, but math is usually absolute.
In 1999, NASA sent the Mars Climate Orbiter on a nine-month, 416-million-mile journey to the Red Planet. It was a masterpiece of engineering. It was designed to surf the upper atmosphere of Mars, acting as a weather satellite and a relay for future landers. It cost $125 million.
On September 23rd, the spacecraft slipped behind Mars to begin its "orbital insertion"—the delicate braking maneuver to enter the planet's gravity. The engineers at the Jet Propulsion Laboratory held their breath, waiting for the signal to return.
It never did.
The orbiter didn't just fail; it vanished. It dipped too low into the atmosphere and disintegrated, burning up like a Roman candle. The investigation that followed revealed the cause, and it wasn’t a failed thruster or a cosmic ray or a rogue alien laser.
It was a failure of translation.
The engineering team at Lockheed Martin in Colorado had programmed the impulse data (the force of the thrusters) in English units: pounds. The team at NASA in California assumed the data was in metric units: newtons. The "Interface Control Document"—the sacred paperwork that defines how the systems talk to each other—explicitly stated that the system should use metric. But the code did not. The map said one thing; the territory said another.
For the want of a conversion factor, the spacecraft was lost.
We like to tell this story as a warning about the importance of double-checking your math. But it is actually a story about the fragility of truth. The documentation for the Mars Climate Orbiter was a lie. It was a high-fidelity, peer-reviewed, officially stamped lie. And that lie cost $125 million.
The Fiction Section of Your Codebase
Most of us aren’t building interplanetary probes. We are building software for HR departments or apps for ordering burritos. When our documentation lies, things rarely explode.
Instead, they rot.
There is a specific kind of madness that comes from following a "README"—the instruction manual for a piece of code—that hasn't been updated since 2022. You download the project. You run the setup command. You get an error message that looks like it was written in Sumerian. You check the docs. The docs say, "Simply run the start script." You run the script. It crashes because it references a database that was deleted three months ago.
You have been gaslit by your own codebase.
This is the "drift." It is the slow, silent divergence between what the code actually does and what the documentation says it does. It happens every time a developer makes a change and thinks, "I'll update the Wiki later." Later never comes. The code moves forward, evolving, mutating, fixing bugs and creating new ones. The documentation stays frozen in time, a snapshot of a reality that has long since passed.
When you allow this drift to happen, you aren't just being lazy. You are actively seeding your organization with traps. You are building a library where every book has the wrong cover.
The Body Count of Bad Handouts
In software, these traps cost us time and sanity. In the physical world, they cost lives.
In 1988, the Piper Alpha oil platform in the North Sea was destroyed in a catastrophic series of explosions that killed 167 men. The disaster had complex causes, but a critical failure point was a missing piece of paperwork. A safety valve had been removed for maintenance, but the "permit to work"—the document tracking that status—didn't make it to the night shift manager’s desk. As noted in retrospective analyses of documentation failures, the documentation was incomplete. The night crew turned on the pumps, not knowing the valve was gone. The gas leaked. The platform burned.
Decades later, the Takata airbag recall—which affected tens of millions of cars and led to at least 16 deaths—was exacerbated by manufacturing processes that had drifted away from the documented standards. The factory floor was improvising. The documentation was a fiction. The result was shrapnel in the cabin, a failure often cited in reviews of industrial documentation hazards.
These are extreme examples, but they illustrate a universal law: Reality does not care about your documentation. Reality only cares about what is actually implemented. If there is a gap between the two, reality wins, and it usually wins violently.
The Silent Malpractice
The most terrifying version of this gap isn't on an oil rig; it's in a hospital.
We have spent billions digitizing healthcare. We have Electronic Health Records (EHRs) that are supposed to be the single source of truth for a patient's life. But anyone who has worked in a hospital knows that the EHR is often a chaotic scrapbook of copy-pasted notes and outdated fields.
A 2024 report found that nearly 20% of medical malpractice cases involve documentation failures. A patient's allergy is buried in a free-text note from three years ago. A medication list includes a drug the patient stopped taking last month. The doctor makes a decision based on the "truth" in the chart, but the chart is lying.
This is the hidden cost of the drift. It isn't just that the new engineer takes three weeks to learn the system instead of one. It is that decisions are being made based on bad data. The map is wrong, but we are still driving the car at 80 miles per hour.
The Entropy of Knowledge
Why do we let this happen? We are smart people. We know that documentation is important. We know that the "bus factor"—the risk that your project dies if your lead engineer gets hit by a bus—is real. Why is our default state one of decay?
It is because we are fighting the second law of thermodynamics. Software is high-entropy. It is constantly changing, breaking, and reforming. Documentation is static. To keep them in sync requires a constant injection of energy.
But we don't reward that energy. We reward shipping. We reward the engineer who fixes the bug, not the one who updates the instruction manual. We view documentation as a tax on speed, a chore to be completed during the "cleanup week" that never actually happens.
So we defer it. We rely on "tribal knowledge"—the oral tradition of the team. "Oh, ask Dave about the billing system," we say. "He knows how it actually works."
Dave is a single point of failure. Dave is a walking liability. And when Dave quits to go work for a trendy AI startup, he takes the truth with him, leaving us with the lies in the Wiki.
The Archaeologist and the Architect
We have tried to solve this with culture. We tell our engineers to "be better." We hire technical writers and put them in a corner, hoping they can chase the train and sketch it while it's moving.
It doesn't work. You cannot solve a systems problem with guilt.
If the problem is that code moves faster than prose, then we need a way to generate prose at the speed of code. We need to stop treating documentation as an artifact of history and start treating it as a continuous output of the build process.
This is the philosophy behind Doc Holiday. We didn't build it because we wanted to automate technical writers out of a job. We built it because we realized that the gap between "work as imagined" (the docs) and "work as done" (the code) was getting too wide for humans to bridge alone.
We need an automated archaeologist. We need a system that watches every change to the code—every update, every deletion, every tweak—and asks: "Does this change the truth?"
When a developer changes a variable from pounds to newtons, an AI should flag that the interface spec is now a lie. It should draft the update. It should scream at the reviewer. It should be the annoying, pedantic, tireless guardian of reality.
The Truth is a Moving Target
The concept of a "static" document is dead. In a world where we deploy new code ten times a day (what the industry calls Continuous Integration/Continuous Deployment, or CI/CD), a document that hasn't changed in a week is probably already suspect. A document that hasn't changed in a month is almost certainly wrong.
We have to accept that keeping the map up to date is not a "nice to have." It is the primary mechanism we have for staying sane in a complex system.
When you look at your documentation, you shouldn't see a dusty archive. You should see a dashboard. You should see the living state of your system, reflected back to you in real-time.
If you don't—if you see a "last updated" timestamp from 2023—then you are walking on ice. You are betting that you remember where the cracks are. You are betting that Dave is still at his desk.
You are betting against the entropy of the universe. And eventually, the house always wins.
The Mars Climate Orbiter didn't know it was doomed. It just followed its instructions. It believed the lie.
Don't let your team burn up in the atmosphere because you were too busy to update the units.
