The interface should explain itself before the docs do
Documentation is where you go when the interface gave up, and the goal is to make that trip rare.
Documentation feels like a feature. You write it, you ship it, you point people to it. But every link to the docs is a small admission: the interface couldn't carry the moment on its own, so the user had to leave, read, translate the prose back into clicks, and return. Sometimes that trip is worth it. Mostly it's a tax we charge users for a decision we didn't make in the UI.
I've started treating the docs as a measurement, not a deliverable. The questions people ask in support, the sections they search, the steps they screenshot and send to a teammate — those are a map of every place the interface stopped explaining itself. The goal isn't better docs. It's fewer reasons to open them.
The interface knows things the prose has to repeat
When a button needs a paragraph to explain what it does, the paragraph is patching the button. That paragraph will drift. The button ships in v3, the docs describe v2, and now the most authoritative-sounding source in your product is quietly wrong. Prose decays because it lives somewhere the code doesn't.
A label, a default, an inline hint, a disabled state with a reason attached — those live next to the behavior they describe. They can't lie for long, because the same person who changes the behavior is looking right at them. The closer an explanation sits to the thing it explains, the longer it stays true.
So before writing a doc, I ask what the interface is failing to say:
- →A field labeled "Region" that needs a sentence about which regions support which features should say so where you pick it.
- →A destructive action that needs a warning in the docs needs a confirmation step in the product.
- →A setting whose effect is invisible until tomorrow's billing cycle should tell you that at the moment you flip it.
Each of those is a doc you don't have to write, and a question you don't have to answer twice.
Good defaults are documentation you don't have to read
The most underrated form of explanation is a choice the user never has to understand. A sensible default says, in effect, "you don't need to know what this does yet." The advanced path is still there for the person who needs it, but the common case carries no homework.
A setting that ships with a good default is a paragraph nobody has to read.
This is where empty states, placeholder examples, and the first-run experience do more than any onboarding guide. A form field pre-filled with a realistic example teaches the format faster than a rule ever could. An empty table that shows what a populated row will look like answers the "what goes here" question before it's asked. The interface demonstrates instead of describing, and demonstration doesn't drift.
Docs are the deep end, not the entrance
None of this means delete the documentation. Some things genuinely need it: the conceptual model behind a system, the why behind a constraint, the reference you scan when you're already three layers in. That's real work and it deserves real prose. The mistake is using docs to cover for an interface that mumbles.
A useful test: read your own docs and underline every sentence that exists only because the product didn't say it at the right moment. "Make sure to save before navigating away." "Note that this cannot be undone." "You must enable X before Y will appear." Each of those is a UI fix wearing a documentation costume. The sentence is cheap to write, which is exactly why it's the wrong tool — it lets you defer the harder, better fix into a place the user has to go looking for.
The honest version of a product treats every visit to the docs as a small failure to learn from. Not a failure to feel bad about — most are reasonable, and some are unavoidable — but a signal worth logging. Where did the interface run out of things to say? That's your next piece of work, sitting in plain sight.
Build the product so the docs are where curious people go deeper, not where confused people go to survive.
