Nobody dislikes your documentation out of spite. They dislike it because they can't find what they need in it, and when they do find it, it's explained in a way that assumes they already understand half of what they're looking up.
That's really the whole diagnosis: most technical documentation is written by an engineer talking to another engineer, and most of its readers aren't there yet. UX writing — the discipline of writing interface and product copy around what a user is actually trying to do — has a lot to offer documentation, because it starts from the same premise interface designers work from: the reader isn't here to admire your system, they're here to get something done and leave.
A few patterns show up again and again in documentation that fails: no obvious entry point (a two-hundred-page wiki with no map), too much scene-setting before any instruction ("five paragraphs before the first actionable line), jargon that assumes fluency the reader doesn't have, sections that don't say who they're for or why, and — maybe the most common one — no confirmation that the reader's action actually worked. That last one seems small, but it's the reason people re-read the same paragraph three times: they did the thing, nothing told them it succeeded, so they assume they did it wrong.
Lead With the Task, Not the Theory
The reordering that helps more than almost anything else: start with what the reader is trying to do, not with how your system is built. "Here's what you're trying to accomplish" gets someone moving; "here's how the system works" makes them wait for permission to start. Theory has its place, but it belongs after the reader has had a win, not before — put the win first, and offer the deeper explanation as something to opt into rather than something to wade through.
Language That Centers the Reader
| Technical | User-Centered |
|---|---|
| Initialize the webhook | Set up a webhook to receive events |
| Leverage caching layer | Make your app faster with caching |
| Deploy to production | Go live with your changes |
| Execute a query | Find what you're looking for |
The words on the left aren't wrong, exactly — they're just written from the system's point of view instead of the reader's. Swapping "initialize" for "set up," or "execute a query" for "find what you're looking for," costs nothing in accuracy and buys a lot in accessibility. I'd apply this filter to every heading and every button label a doc references, not just the prose.
Information architecture is the other half of this: task-based sections instead of a structure that mirrors your internal system architecture, a hierarchy shallow enough to scan, and navigation that actually links related pages together instead of leaving readers to guess what else exists. A workable shape for most documentation sites is a quick-start section for the five-minute win, task-based guides for the common jobs people come back for, a reference section for the exhaustive detail, and a concepts section for the "how this actually works" material that most readers will skip on their first visit and come back to later.
For any individual page, the template I'd default to is: title, a one-line statement of the goal, prerequisites, numbered steps, a working code example, what to do next, and a troubleshooting note for the ways it commonly goes wrong. Not every page needs every part, but that's the order that matches how someone actually reads a task-oriented doc.
Small Writing Habits That Add Up
Active voice ("upload the file," not "the file should be uploaded") and short sentences do a surprising amount of the work on their own. Progressive disclosure — revealing complexity gradually instead of front-loading it — keeps a page approachable for a beginner without dumbing it down for someone who wants the detail; they just keep reading past the point where a beginner would stop. And the confirmation habit I mentioned earlier matters more than it gets credit for:
| Without | With |
|---|---|
| Update your settings | Your settings are now saved |
| Run the test | All tests passed (3 of 3) |
| Deploy | Deployment successful |
The right column tells the reader the outcome, not just the action — which is exactly the information they're looking for in the three seconds after they click something.
Beyond that, a few small conventions save a lot of confusion: reserve H1 for the page topic, H2 for major sections, H3 for detail within a section — no deeper than that if you can help it, since deep nesting is usually a sign the page should be split in two. Tables are great for comparing options or listing parameters; they're a poor fit for sequential instructions or plain lists, where the ordering and flow of prose or a numbered list carries meaning a table's grid structure destroys.
Docs Decay — Plan for It
Documentation drifts out of date the moment the underlying product changes and nobody updates the page — and in my experience, the gap between "slightly stale" and "actively misleading" closes faster than most teams expect, especially right after a release that touches core workflows. The fix isn't heroic effort, it's structural: tie a documentation review to your release process rather than treating it as a separate, easily-deprioritized task, show a last-updated date so readers can judge freshness for themselves, and give people a low-friction way to flag a page that's wrong. A visible feedback mechanism catches drift faster than any internal review cadence, because your users hit the wrong page long before your team happens to notice.
A Short Audit Worth Running on Your Own Docs
Pick one page and ask honestly: can a new user find their first task within about ten seconds of arriving? Is the quickest path to success obvious rather than buried? Can they copy-paste a working example straight from the page? Does it explain why, not just how, at least once? Is it actually scannable, or does it read as one dense block? And do the examples work exactly as written, right now, on the current version of the product?
If most of those come back "yes," the page is in good shape. If more than a couple come back "no," that's your starting point — not a sign to rewrite everything, just the specific page and the specific gap to fix first.
The best documentation doesn't exist to showcase how the system works. It exists to get someone unstuck as fast as possible and then get out of their way. Start with one page, apply what actually applies to it, and let the rest follow from there.