BeCuriouzLearn something new every day
Why experts often write the worst documentation
💡 The better you know a system, the harder it is to see what a beginner doesn't know — so great docs are written for the reader's starting point, not the author's.
It seems backwards, but the person who knows a system best is often the worst at explaining it. The reason is a mental blind spot called the curse of knowledge — once you deeply understand something, you literally can't remember what it was like to not understand it. So expert authors skip the 'obvious' steps, drop unexplained jargon, and assume context the reader has never seen.
This is why great documentation is written for the newcomer, not the author. The fix isn't more detail — it's empathy for the reader's starting point. Good docs spell out prerequisites, define terms on first use, and never say 'simply' or 'just' (words that quietly shame a stuck reader). They show a complete, copy-pasteable example instead of a fragment that assumes you know where it goes.
The most reliable cure is testing your docs on a real beginner. Watch someone follow your instructions without helping them. Every place they get stuck reveals a hidden assumption your expertise made invisible. That friction — not your confidence — is the true measure of whether the documentation works.