The Author Is the Worst Judge of Their Own Docs

I’ve written onboarding docs I was proud of — clear steps, sensible order, everything a new engineer needs to get set up and productive. Then I watched an actual new person try to follow one, and it fell apart at step two on an assumption I didn’t even know I was making. That’s not a knock on the doc or the reader. It’s a structural fact: the author is the single worst judge of whether their own documentation works, because they can’t un-know the things that make it read as obvious. The only reliable test is someone who doesn’t have that context, following it cold.

The curse of knowledge is invisible from the inside

Once you know something, you can’t remember not knowing it. So when you write the setup guide, the prerequisite that “everyone has” doesn’t get mentioned, the tool that’s “obviously” installed already is assumed, and the link you find in two clicks because you know where it lives becomes “grab the config from the usual place.” Every one of those is a cliff to a newcomer and invisible to you, because your brain silently fills the gap every time you re-read your own words.

You can proofread your doc a hundred times and never see the missing step, because you perform it automatically every time you read past it.

This is why documentation feels fine to the author and frustrating to the audience. The author is testing it against a brain that already has the answers. The audience is testing it against the one that doesn’t — which is the only test that counts.

Onboarding docs rot the fastest

Of all documentation, onboarding and setup guides decay quickest, and the curse of knowledge is why. They’re written by people deep in the system for people who aren’t, so they start out riddled with unstated assumptions. Then the environment drifts — a tool changes, a step becomes unnecessary, a new one appears — and the author, who no longer does onboarding, never feels the breakage. The doc quietly diverges from reality, and the only people who hit the divergence are newcomers with no standing to know it’s the doc that’s wrong and not them. So they struggle silently, assume they’re the problem, and the doc keeps its undeserved reputation for being fine.

The newcomer is the test suite

There’s exactly one dependable way to find the gaps: hand the doc to someone without the context and watch them run it, ideally without helping. Every place they pause, ask a question, or guess is a defect — not in the reader, in the doc. The value is in the stumbles, so the hardest and most important discipline is to not jump in and explain. The instant you say “oh, you just need to also…,” you’ve patched the person instead of the document, and the next newcomer hits the same wall.

Bite your tongue, write down where they got stuck, and fix the doc there. A guide that’s survived a couple of real people following it cold is worth ten that only their author has ever read.

Writing it down is only the first pass

Writing the doc is genuinely useful even before anyone tests it — the act of writing forces you to make implicit steps explicit and exposes gaps you’d otherwise skate over, which is the whole argument in writing the runbook is the test. But writing catches the gaps you can see. The curse of knowledge is precisely the set of gaps you can’t, and only a different brain surfaces those. So the two tests stack: writing it down catches what you know you don’t know; a newcomer running it catches what you don’t know you know.

Treat the doc as living, and its assumptions as bugs

The habits that come out of this:

• Have a real newcomer run it, and shut up while they do. Their confusion is your bug report. Their questions are your missing steps.
• Hunt your own assumptions on purpose. Before publishing, reread asking “what does the reader have to already know or have for this step to work?” — and write that down.
• Give the doc an owner and a pulse. An onboarding guide nobody re-runs is drifting from reality right now; treat it as infrastructure that has to be maintained, not a one-time artifact.
• Make it cheap for readers to report friction, because they’re the only ones who can see what you can’t.

The uncomfortable truth is that your confidence in your own doc is worth almost nothing — it’s measuring your knowledge, not the doc’s clarity. The reader who doesn’t already know the answer is the only instrument that measures the right thing. Point that instrument at your docs on purpose, and stop trusting your own read of them. If you’ve watched a newcomer expose everything wrong with a guide you were sure was clear, I’d love to hear about it.