Craft
Teach the thing you learned last week
The best person to explain a concept is rarely the expert. It is someone who was confused about it recently enough to remember why.
01Expertise makes you a worse explainer
Once something is obvious to you, you cannot reconstruct what it was like when it was not. The expert skips the step that was the actual obstacle, because to them it is not a step. That is why so much documentation is technically complete and practically useless.
Someone who was stuck on it three weeks ago still remembers the specific wrong mental model they had. That wrong model is the most valuable thing they own, and it has a short shelf life.
02What makes an explanation land
- Lead with the wrong assumption you were making. Readers holding the same one will recognise themselves immediately.
- Show the failing case before the fix. A bug someone can reproduce beats a paragraph of theory.
- Say what you still do not know. It is honest, and it tells the reader where the edge of the map is.
- Keep the scope to one idea. "Everything about caching" helps nobody; "why your data is stale after a mutation" helps somebody today.
03The selfish argument
Writing an explanation is the fastest way to find out you do not understand something. The moment you have to produce a working example, the fuzzy parts stop being fuzzy and start being errors. I have abandoned more than one draft because writing it revealed I had the mechanism backwards — which is a cheap way to find out, compared to shipping it.
That is most of why the Learn section of this site exists. It is a byproduct of checking my own work, and it happens to be useful to other people.