The Curse of Knowledge: Why Experts Write Bad Documentation

A new engineer opens the README on their first day and reads: "Run the usual setup, then point it at staging and you're good to go." There is no link to "the usual setup," no note on which staging, no hint at how to point anything at it. The person who wrote that line was not being lazy. To them, every step was obvious, because they had done it a hundred times and could no longer imagine a reader who had not.

That is the curse of knowledge, and it is the single most expensive bias in technical writing. The gap between what a writer knows and what a reader needs is invisible to the writer, precisely because they already crossed it. It has a mirror image on the reader's side: we keep trusting a source we just caught being wrong, extending the credit it earned in one area to every other.

What is the curse of knowledge?

The curse of knowledge is a cognitive bias where someone who knows something well becomes unable to imagine what it is like not to know it. Once a fact is in your head, your brain quietly assumes it is in everyone else's too, so you skip the context, the definitions, and the steps that feel too obvious to mention. They are only obvious to you.

Economists Colin Camerer, George Loewenstein, and Martin Weber named the effect in 1989, studying why better-informed traders kept mispredicting how less-informed people would behave. Chip and Dan Heath later popularized it in Made to Stick as the reason clear ideas so often fail to travel. The bias is not about intelligence or effort. The more expert you are, the stronger it gets, which is exactly what makes it dangerous for the people who write the most documentation: the ones who know the system best.

For a note-taking and documentation tool like Scribelet, the curse of knowledge is not an abstraction. It is the mechanism behind almost every stale README, unfollowable runbook, and onboarding doc that assumes you already know the thing it was supposed to teach. We come back to what to do about that at the end.

The tapper and the listener

The clearest demonstration of the curse comes from a 1990 Stanford experiment by Elizabeth Newton. Participants were split into "tappers" and "listeners." Each tapper picked a famous song like "Happy Birthday" and tapped out its rhythm on a table. Then they guessed how often the listeners would name the tune.

Tappers predicted listeners would get it right about 50 percent of the time. The listeners actually identified the song 2.5 percent of the time.

The tappers were not fools. They simply could not un-hear the melody playing in their own heads while they tapped. To them the rhythm obviously carried the song, because they had the song. The listeners heard a stranger drumming randomly on furniture. That is the curse of knowledge in one experiment: the tapper cannot experience the taps the way a listener does, so they wildly overestimate how much got across. Every expert writing documentation is a tapper convinced the melody is obvious.

The curse of knowledge in software and documentation

Software teams run on written knowledge, which means they run straight into this bias constantly. It shows up in a handful of recognizable shapes:

• READMEs that skip the setup that matters. "Just configure your environment and run the tests." Which variables? Configured how? The author knew, so they compressed a twenty-minute process into six words.
• Onboarding docs written by people who onboarded years ago. They document the system they wish existed, or the one they remember, not the messy one a newcomer actually meets on day one.
• Code comments that assume the reader shares your context. A comment that says "handle the edge case" is only useful to the person who already knows which edge case and why it is special.
• Tickets and design notes nobody outside the team can parse. Internal shorthand, unexpanded acronyms, and references to a Slack thread from last quarter that the reader was never in.
• The reasoning left out entirely. The hardest version: the author knew why a decision was made, assumed that why was self-evident, and wrote down only the what. The reasoning was obvious to them, so it never made it to the page.

Every one of these is the tapper problem. The writer hears the full melody. The reader gets isolated taps and is expected to reconstruct the song.

Where the curse shows up, and what it costs

The bias is easier to catch when you name the specific assumption behind each symptom. The pattern is always the same: the expert assumes the reader shares a piece of context, and the reader, missing it, is left stuck.

The cost is not just a confused reader. It is the support question that pulls a senior engineer off their work, the onboarding that takes three weeks instead of one, and the decision that gets silently reversed because nobody recorded why it was made. The curse of knowledge is the reason code shows the what but rarely the why: the person writing it could see the reasoning so clearly that writing it down felt redundant.

How to break the curse of knowledge

You cannot un-know what you know. The tapper cannot make the melody stop. What you can do is build habits that route around your own blind spot, because the fix is never "try to remember what it was like to be a beginner." You will fail at that. The fix is to get the missing perspective from outside your own head.

1. Run the beginner test. Before you call a doc done, hand it to someone who does not already know the answer, and watch where they get stuck. Their confusion is the data. Do not explain it away in the room; write down the step they tripped on and fix the doc. When you cannot borrow a beginner, explaining the work out loud to no one in particular is the next best thing, because saying each step forces the assumption you were silently skipping into the open.
2. Expand every acronym and define every term the first time. If a word is load-bearing and specific to your system, it needs one sentence of definition. This feels patronizing to write and is invaluable to read.
3. Write the why, not just the what. For any non-obvious decision, record the reasoning and the constraint that forced it. The reasoning behind a decision is exactly the part your future readers cannot reconstruct from the result alone.
4. Name the prerequisites out loud. Access, tools, permissions, prior steps. If a reader needs something before step one, step zero should say so.
5. Assume the reader has none of your context, not all of it. When in doubt, over-specify the setup and under-specify nothing that matters. A reader who already knows can skim past a paragraph. A reader who does not cannot invent the paragraph that isn't there.

None of this requires more talent. It requires treating your own fluency as a liability during writing, not an asset.

A worked example: the mystery config value

Say you are documenting a service and you write: "Set RETRY_BUDGET appropriately for the environment." To you that sentence is complete, because you know the budget trades off latency against transient failures and that production runs hot. To the reader it is a dead end. Appropriately how? Compared to what?

Here is the same line rewritten against the curse. "Set RETRY_BUDGET to the number of retries a request may make before failing. Staging uses 3. Production uses 8, because the downstream billing API has a documented cold-start delay that 3 retries does not cover. If you lower it in production, expect intermittent failures during low-traffic periods." The second version is longer, and every extra word closes a gap the first version left the reader to fall into. The only reason the first version felt sufficient is that the author could already hear the whole melody.

The trap: do not overcorrect into noise

Breaking the curse is not a license to explain everything to everyone forever. A doc that defines "database" for a team of database engineers has swung past the reader and into condescension, and nobody reads a page that treats them like they know nothing.

The bias to avoid on the other side is a cousin of the curse, not its opposite: over-explaining because you imagine the reader knows less than they do. The target is not maximum detail. It is calibration to a real reader, which is why the beginner test beats introspection every time. You are not trying to write for an infant. You are trying to write for the specific person who will actually open this doc next, and the only way to know what they need is to find one and watch.

Why writing it down is the only real fix

The curse of knowledge would not matter much if the knowledge stayed in the expert's head and the expert stayed forever. It matters because neither is true. People rotate off projects, forget their own reasoning, and leave. When the only copy of why a system works the way it does lives in one person's memory, you do not have documentation, you have a bus factor of one wearing a lanyard.

And even the knowledge that does get written down decays. The curse makes writers omit the context that dates a decision, so a doc that was merely terse on the day it was written becomes actively misleading a year later, once the constraint it silently assumed has changed. This is the same failure behind outdated documentation and the broader problem of notes going stale: the reasoning expired, but nobody wrote the reasoning down, so nobody can tell. Capturing the why the moment you know it, in an internal documentation habit rather than a heroic annual cleanup, is what turns a tapper's private melody into something a listener can actually hear.

Scribelet is built for that gap. When you capture the reasoning behind a decision or a setup step as you make it, that note becomes the context the curse of knowledge would otherwise strip out. The discipline is small and specific: write the constraint that forced the choice, not just the choice, and write it in a durable place rather than a Slack thread that scrolls away by next week. Background agents then re-check what you wrote against reality on a schedule, so when the constraint that justified a config value changes, you get a diff instead of a doc that quietly lies to the next person who reads it. The point is not to write more. It is to write the one sentence your own expertise keeps telling you is too obvious to bother with, because that sentence is the whole melody the reader cannot hear.

Getting started

The next time something feels too obvious to write down, treat that feeling as the warning sign it is. That is the curse of knowledge telling you the reader will need exactly the thing you are about to skip. Write the why, name the prerequisite, define the term, and hand it to someone who does not already know. Try Scribelet free and give the reasoning behind your work somewhere durable to live, before the person who understood it moves on and takes the melody with them.