Documentation isn't about being clear. It's about empathy. Here's what I've learned about helping people understand complex technical concepts without making them feel stupid.
I used to think good documentation was about being concise. Remove the fluff, get to the point, right?
Turns out I've been thinking about it backwards for years. The best documentation isn't written at all. It's empathized into existence. You have to feel what it's like to not know something before you can explain it.
Here's what changed how I think about writing technical docs.
A few months ago I was struggling to explain something simple. I kept writing:
First, install the dependency with npm install. Then configure your config file...
And people's eyes would glaze over because I was asking them to hold too many things in their head at once.
I started reading about cognitive load theory (yes, that's a real thing) and something clicked: documentation is an exercise in empathy, not description.
Your brain has a limited amount of processing power available at any moment. Think of it like RAM — you can only hold so many items before things start dropping.
Bad documentation fills up that RAM fast:
Good documentation keeps more RAM free:
This is the hardest part: once you understand something, you forget what it felt like to not understand it.
I remember spending a full day debugging a race condition in a Node.js service. Requests were intermittently returning stale data, and I was convinced it was a caching bug. It wasn't. Two async handlers were both writing to the same shared object without awaiting each other, and the second one was occasionally resolving first. The fix was a single await in the right place. Now when I write "just make sure your async operations are properly sequenced," I sound like someone who has never stared at a network tab for six hours wondering why the same endpoint returns two different responses on back-to-back calls.
The fix isn't to explain more. It's to remember your own confusion and write from there.
Most documentation does this:
"Use the config() function to configure your settings."
That's a solution looking for a problem. What settings? Why would I want to configure anything?
Try this instead:
"If you need your API to behave differently in development versus production, use config() to set environment-specific values."
Now I understand why I'd ever want to use it. The solution has context.
Here's a weird trick: when you're writing, ask yourself "what would confuse me?"
Last week I wrote:
"Initialize the client with your API key."
But I caught myself thinking: "wait, where do I get an API key? What format does it need to be in?"
So I added:
"Get your API key from the dashboard under Settings → API Keys. It's a UUID format."
These questions aren't weaknesses in the documentation. They're the actual content.
I owe a lot of this thinking to reading Dan Abramov's blog (overreacted.io). His posts taught me that:
He writes as if he's figuring things out with you, not at you. That's the voice I want.
Technical writing isn't about being right. It's about being in the trenches with your reader.
Next time you're writing docs, ask: "if I forgot everything about this topic, would this help me?"
If the answer is no, start over. Your future confused self will thank you.
Thanks for reading. If this resonated, I'd love to hear what confused you this week.