Photo by ThisIsEngineering on Pexels.
There’s a specific feeling you get when documentation actually works.
It’s not relief, exactly. It’s more like the feeling of asking a question and getting a straight answer from someone who knows what they’re talking about. Someone who anticipated what you needed, skipped the parts you already knew, and told you what to do without talking down to you.
That feeling is rare. We’ve all encountered documentation that doesn’t produce it.
What Documentation Often Sounds Like
Too much documentation sounds like it was written by someone covering their bases.
It’s comprehensive in ways that don’t help you. It defines terms you already know and skips the ones you don’t. It tells you what a feature does without telling you when to use it. It protects the writer from being wrong by never quite saying anything directly.
You’ve read this documentation. You’ve probably also given up on it and gone looking for a forum post or a YouTube video where someone just tells you what to do.
The Knowledgeable Colleague Standard
Think about the last time you learned something complicated at work. Not something you looked up from a manual, but something you learned from a person.
That person probably didn’t start at the beginning and explain everything in order. They intuited what you already knew and started there. They used the names your team actually uses for things. They told you the step that everyone gets wrong. They mentioned the thing you only need to worry about if you’re doing the advanced version of the task.
And when they were done, you could do the thing.
That’s the standard.
Not comprehensive. Not legally defensible. Not consistent with the template.
Useful to the specific person trying to do a specific thing right now.
What It Takes to Write That Way
The knowledgeable colleague isn’t winging it. They know the subject deeply enough to know what to leave out. That’s the hard part.
Deciding what to leave out requires judgment. Judgment requires understanding your audience well enough to know what they already know, what they’re trying to accomplish, and where they’re most likely to get stuck. You can’t write toward a person you haven’t thought about.
This is why good documentation is hard to produce by committee, hard to generate purely with AI, and hard to maintain when writers are too far removed from the people using the product. It requires someone who has done the work of understanding both the thing being documented and the person who needs to use it.
The Test
Before publishing anything, I recommend that you ask a simple question:
If a capable, intelligent person who didn’t already know this sat down and read it, could they do the thing?
Not “could they find the information?”
Could they do the thing?
If the answer is no, it needs more work. If the answer is yes, it’s probably good enough. And it’s probably good enough even if the doc is not exhaustive, doesn’t cover every edge case, or if someone could quibble with the structure.
Documentation that helps people do their jobs is the whole job. Everything else is secondary.