Chapter 1 · Practice 2 of 4
Fight the curse of knowledge: explain what feels obvious to you
Why it matters
The course names the main trap for expert writers: the curse of knowledge. Experts forget what newcomers do not know, so their explanations skip steps, terms and context that a newcomer needs.
Signs you have fallen into it:
- Acronyms and internal names with no definition.
- Steps like "set up the environment" with no detail.
- Jumps from the problem to the solution with no reasoning in between.
Fixes:
- Define every term the first time you use it, or link to a definition.
- Ask someone new to follow your doc while you watch silently.
- Note every question they ask; each one is a gap in the doc.
Do
- Test docs on someone who has never seen the system
- Define acronyms on first use
Avoid
- Assuming internal names and shortcuts are common knowledge