I found an onboarding doc I wrote in 2018. It says install Go 1.8. The service it covers was running Go 1.11 by the time I wrote it, and 1.11 had been out for months. The doc was wrong on the day it was written.
That’s not negligence. That’s the date. Go 1.8 was the version the team started the service on. That was the setup everyone knew. The doc captured what was in the air, not what was in the go.mod. I wrote it, and I was wrong, and at the time I didn’t notice the gap. Neither did the three engineers who used it after me. The doc said 1.8, they installed 1.8, the build server didn’t care, nothing broke.
Onboarding docs drift. They’re written by the person who last had to explain the system from scratch. Usually someone who recently joined. Or someone who just onboarded someone else and realized nothing was written down. Whoever writes it is calibrated for the environment at the moment of writing. The next person who reads it inherits a slightly different world. The person after that inherits another. Nobody updates it after they’re onboarded. Their job is done. They’re writing code now. The doc did its job for them and they have no reason to revisit it.
The drift is structural. The artifact is written once and read forward. People have no incentive to correct it. The environment changes in ways the author couldn’t predict.
And it’s worse than that. The author is the person least qualified to write the doc. They just learned the system. They don’t know which parts are stable and which are accidental. They don’t know which assumptions will survive the next refactor. They’re writing down what worked for them, on their machine, on the day they got it running. A year later the setup script has changed, the build dependency versions have been bumped, and the one weird step in the README that was actually load-bearing is surrounded by ten other weird steps that were the author’s local setup. The next person has to figure out which is which.
The drift is the information. Not the doc you want, but the doc you have. Read it and you can date it.
A doc that says install Go 1.8 when every service in the org is on 1.11 or newer. That tells you the migration happened after the doc was written. No one updated it. No one noticed. Either the migration was seamless or the engineers who understand the new setup haven’t touched this doc since they joined - the doc stopped being the canonical setup path and became something else, living somewhere else. In someone’s head. Either way, the direction is the information.
A doc with a multi-paragraph setup section for a component that’s two lines to configure today tells you it used to be hard. Someone carried the pain forward into the document. The engineer who wrote it fought with Consul ACL tokens for half a day, got it working, and wrote down every step so the next person wouldn’t suffer. Six months later someone automated the token provisioning and the setup became consul agent -config-file=... but the doc still has the twelve-step manual process. The doc is a scar. The scar is useful, it tells you what the old infra demanded and what the new infra solved, but you have to read it as a scar, not as a procedure.
A missing section is the most diagnostic thing in the doc. A setup guide that explains how to get the service running locally but has no section on how deploys work. A doc that explains the service’s directory layout but never mentions the message queue it depends on. A doc that references “the on-call rotation” without linking to it. Each missing section is a piece of knowledge the author took for granted, they either already knew it, or someone told them and they didn’t realize it was something the next person would need written down. That knowledge is tacit. Which means it lives in one or two people. It’s a bus-factor flag you don’t have to run a survey to discover. You have to read the table of contents and notice what isn’t there.
Then there’s the # TODO: add more context here. I had one of these. I wrote it. I was the person who didn’t understand the thing well enough to explain it, so I left a marker and told myself I’d come back. I didn’t come back. That TODO sat in the doc for two years, through three new hires, each of whom read it, understood that the person before them didn’t understand, and either figured it out themselves or asked around. The TODO was the most honest line in the document. It said: I ran out of time, and this part was hard for me, and I’m naming that gap instead of filling it with words that would’ve been wrong.
The config file records what the machine survived. The git log records what the team decided. The onboarding doc records what someone was willing to explain to a stranger while they still remembered what it felt like not to know.
The wrongness is the only part you can trust. The instructions might work. The version numbers are probably stale. But the gaps, the drift, the TODO the author never resolved. Those are the parts nobody fabricated. Nobody lies in a TODO marker. Nobody pretends to know a version number and gets it wrong on purpose. The onboarding doc’s honesty is in what it fails to say, and what it says wrong, and what it admits it can’t explain. Read it for that.