Thoughts
Good documentation respects the reader’s intelligence while acknowledging what they don’t know yet.
I didn’t always think this way. I used to assume that if I understood something, explaining it would be easy. But clarity doesn’t come from intelligence, it comes from empathy.
Writing for beginners without dumbing things down
When I write documentation, I start by asking: what’s the minimum viable mental model someone needs to be productive?
The goal isn’t to oversimplify. It’s to remove unnecessary cognitive load. I introduce that foundational model with the simplest possible example, then build complexity progressively. Each new concept builds on what came before.
This isn’t supposed to be handholding, it’s just a good pedagogy.
Progressive examples teach judgment, not just syntax
Most docs give you two things: a “hello world” example and a production-ready configuration. The gap between them is where real learning happens.
I try to show the progression: here’s the basic version, here’s why you might need more, here’s what that looks like. Walking readers through this journey teaches judgment, when to use what, and why.
Precision matters more than length
I’d rather have brief, accurate documentation than long, hand-wavy explanations. If I can’t explain something precisely, that’s a sign I don’t understand it well enough yet.
Precision doesn’t mean jargon. It means saying exactly what you mean and nothing else. Short sentences. Clear structure. No filler.
Never promise what the code can’t deliver
Documentation should be honest. If a feature has limitations, say so upfront. If an API has rough edges, document them clearly.
Users will forgive missing features. They won’t forgive being misled.
Documentation as interface design
The way information is structured teaches users how to think about a system. Good docs don’t just describe features, they reveal the underlying model. They show how pieces fit together and why certain patterns exist.
When documentation is done well, users can predict behavior they’ve never seen documented because they understand the system’s logic.
This is how I approach every piece of documentation I write. Not as marketing, but as teaching. Not as a feature list, but as progressive revelation of how something works and why it matters.
And it’s not just documentation, it’s how I think about building software itself.