--- title: The Biggest Mistake Developers Make When Explaining... description: The 'curse of knowledge' cognitive bias causes developers to write confusing documentation, unclear code comments, and unhelpful explanations — not from... canonical: https://daily.dev/posts/the-biggest-mistake-developers-make-when-explaining-technical-concepts-zslikpc8u twitter:card: summary_large_image twitter:site: @dailydotdev og:type: website og:site_name: daily.dev og:title: The Biggest Mistake Developers Make When Explaining Technical Concepts | daily.dev og:description: The 'curse of knowledge' cognitive bias causes developers to write confusing documentation, unclear code comments, and unhelpful explanations — not from... og:url: https://daily.dev/posts/the-biggest-mistake-developers-make-when-explaining-technical-concepts-zslikpc8u og:image: https://api.daily.dev/og/posts/ZSLiKPc8u.png og:image:alt: The Biggest Mistake Developers Make When Explaining Technical Concepts og:image:width: 1200 og:image:height: 630 og:locale: en --- > ## Documentation Index > Fetch the complete documentation index at: https://daily.dev/llms.txt > Use this file to discover all available pages before exploring further. # The Biggest Mistake Developers Make When Explaining Technical Concepts **[Medium](https://daily.dev/sources/medium_js)** · 7 min read · 0 upvotes · 0 comments ## Summary The 'curse of knowledge' cognitive bias causes developers to write confusing documentation, unclear code comments, and unhelpful explanations — not from arrogance, but because expertise makes foundational concepts invisible to the expert. Using the classic 'tapper/listener' experiment as a frame, seven concrete habits are outlined to close the gap: starting with the problem before the solution, getting real readers to review, letting content sit before rereading, defining every term on first use, replacing abstract explanations with concrete examples, avoiding the phrase 'this part is technical but,' and asking listeners to repeat back rather than just nod. ## Full article daily.dev links to this article rather than hosting it. Read it at the original source: ## Questions this post answers ### What is the curse of knowledge and how does it affect technical documentation? The curse of knowledge is a cognitive bias where someone with specialized knowledge finds it very hard to imagine not having that knowledge, causing them to skip basic concepts and use undefined jargon in documentation. A 1990 Stanford tapping experiment illustrates this: tappers predicted listeners would guess a tapped-out song's rhythm correctly 50% of the time, but the actual rate was 2.5% (3 out of 120), because tappers could hear the full melody in their heads while listeners heard only isolated knocking. _Anyone documenting tools or APIs can find clearer writing habits and developer discussions on daily.dev._ ### What are practical ways to write clearer technical documentation for beginners? Seven concrete habits help close the expertise gap: start with the problem before the solution, get feedback from an actual beginner reader before publishing, reread your own explanation after a few days away, define every term the first time it appears, replace abstract terms with concrete examples, watch for and cut the phrase 'this part is technical', and ask listeners to restate explanations in their own words rather than just nod. _Developers refining how they write READMEs and API docs can trade tips on daily.dev._ ## Similar posts on daily.dev - [How to Talk to Your Coworkers](https://daily.dev/posts/how-to-talk-to-your-coworkers-0toll4v9h) · Ibrahim Diallo · 1 upvotes · 0 comments - [The Biggest Programming Mistakes Beginners Still Make](https://daily.dev/posts/the-biggest-programming-mistakes-beginners-still-make-te2yvdmxn) · Medium · 0 upvotes · 0 comments --- Tags: [#career](https://daily.dev/tags/career) [View this post on daily.dev](https://daily.dev/posts/the-biggest-mistake-developers-make-when-explaining-technical-concepts-zslikpc8u) ```json {"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://daily.dev/#organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180},"sameAs":["https://twitter.com/dailydotdev","https://github.com/dailydotdev","https://www.linkedin.com/company/daily-dev-ltd"]},{"@type":"WebSite","@id":"https://daily.dev/#website","url":"https://daily.dev","name":"daily.dev","publisher":{"@id":"https://daily.dev/#organization"},"potentialAction":{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https://daily.dev/search?q={search_term_string}"},"query-input":"required name=search_term_string"}}]} {"@context":"https://schema.org","@type":"TechArticle","headline":"The Biggest Mistake Developers Make When Explaining Technical Concepts","url":"https://daily.dev/posts/the-biggest-mistake-developers-make-when-explaining-technical-concepts-zslikpc8u","mainEntityOfPage":{"@type":"WebPage","@id":"https://daily.dev/posts/the-biggest-mistake-developers-make-when-explaining-technical-concepts-zslikpc8u"},"datePublished":"2026-07-21T19:30:57.512Z","dateModified":"2026-09-13T18:27:31.392Z","description":"The 'curse of knowledge' cognitive bias causes developers to write confusing documentation, unclear code comments, and unhelpful explanations — not from...","image":"https://media.daily.dev/image/upload/s--OHB84bZF--/f_auto/v1722860399/public/Placeholder%2010","thumbnailUrl":"https://media.daily.dev/image/upload/s--OHB84bZF--/f_auto/v1722860399/public/Placeholder%2010","isAccessibleForFree":true,"articleSection":"Medium","inLanguage":"en","publisher":{"@type":"Organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180}},"author":{"@type":"Organization","name":"Medium","logo":"https://media.daily.dev/image/upload/t_logo,f_auto/v1/logos/medium","url":"https://daily.dev/sources/medium_js"},"commentCount":0,"discussionUrl":"https://daily.dev/posts/the-biggest-mistake-developers-make-when-explaining-technical-concepts-zslikpc8u","interactionStatistic":[{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":0},{"@type":"InteractionCounter","interactionType":{"@type":"CommentAction"},"userInteractionCount":0}],"keywords":"career","timeRequired":"PT7M"} {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://daily.dev"},{"@type":"ListItem","position":2,"name":"Medium","item":"https://daily.dev/sources/medium_js"},{"@type":"ListItem","position":3,"name":"The Biggest Mistake Developers Make When Explaining Technical Concepts"}]} {"@context":"https://schema.org","@type":"FAQPage","@id":"https://daily.dev/posts/the-biggest-mistake-developers-make-when-explaining-technical-concepts-zslikpc8u#faq","mainEntity":[{"@type":"Question","name":"What is the curse of knowledge and how does it affect technical documentation?","acceptedAnswer":{"@type":"Answer","text":"The curse of knowledge is a cognitive bias where someone with specialized knowledge finds it very hard to imagine not having that knowledge, causing them to skip basic concepts and use undefined jargon in documentation. A 1990 Stanford tapping experiment illustrates this: tappers predicted listeners would guess a tapped-out song's rhythm correctly 50% of the time, but the actual rate was 2.5% (3 out of 120), because tappers could hear the full melody in their heads while listeners heard only isolated knocking. Anyone documenting tools or APIs can find clearer writing habits and developer discussions on daily.dev."}},{"@type":"Question","name":"What are practical ways to write clearer technical documentation for beginners?","acceptedAnswer":{"@type":"Answer","text":"Seven concrete habits help close the expertise gap: start with the problem before the solution, get feedback from an actual beginner reader before publishing, reread your own explanation after a few days away, define every term the first time it appears, replace abstract terms with concrete examples, watch for and cut the phrase 'this part is technical', and ask listeners to restate explanations in their own words rather than just nod. Developers refining how they write READMEs and API docs can trade tips on daily.dev."}}]} ```