Every "how do I authenticate?" question that lands in a support queue costs someone real time to answer, and if a documentation gap generates that question a thousand times a month, that's a real ongoing cost rather than a one-off inconvenience. The frustrating part is that most of those tickets are answering something that could have been answered by a page the developer never found, or a page that didn't exist yet.
Developers reliably say they'd rather find an answer in the docs than wait on support — API and SDK documentation is consistently the resource developers reach for first. That preference is the whole business case for investing in docs: every question a developer can self-serve is a support conversation that never has to happen, and a developer who found their own answer in thirty seconds is in a much better mood about your product than one who waited half a day for a reply.
Structuring Around the Questions People Actually Ask
I've found it's more useful to organize documentation around the sequence of questions a developer works through than around your internal product structure. It roughly goes: "how do I get started" (installation and setup — system requirements, step-by-step install, a way to verify it worked, and what to do if it didn't), "how does this thing think" (core concepts — terminology, architecture, what the tool is and isn't, so people stop guessing), "can I get something working in five minutes" (a genuine quick start, not a curated tour), "what are all my options" (the full reference, with real gotchas and edge cases, not just a parameter list), "how do I do this real task" (task-oriented guides with copy-pasteable code), and finally "why isn't this working" (a troubleshooting section organized by the actual error text, since that's what people paste into search).
That last one deserves special attention, because it's the section people reach for at their most frustrated. When a developer hits an error, they search for the literal error string — not a paraphrase of it. If your troubleshooting section doesn't contain the exact text your tool outputs, it won't show up in that search, no matter how good the explanation underneath it is.
Structuring Each Page
Within any given page, I write with the assumption that most readers are scanning, not reading start to finish: lead with what the thing is, follow with why it matters, then the details, then a working example, then a pointer to what's related. Layering the depth this way — a one-sentence summary, then a paragraph, then the full detail, then advanced edge cases — lets someone stop reading as soon as they have what they need, instead of forcing everyone through the same depth of explanation regardless of what they actually came for.
Code examples are worth extra care. Nobody wants to adapt a foo/bar example to their real problem — realistic variable names and real-shaped data make the difference between an example someone can copy and run versus one they have to mentally translate first. Show the expected output too, so someone can tell immediately whether it worked.
Knowing Whether It's Working
The metrics I'd actually watch: whether support tickets referencing a given topic are trending down after you improve that page, whether time-to-first-success in onboarding is improving, and whether your own documentation shows up when you Google the exact questions people ask about your product. That last one is a good gut check — if your docs don't appear in the first few results for a common question about your own tool, they're not reaching the people asking it, no matter how good the content is once someone finds it.
Mistakes Worth Naming
The one I see most is assuming prior knowledge — "just use the import statement" assumes the reader already knows how, which defeats the purpose of writing it down at all. Outdated examples are a close second, and they're corrosive to trust in a specific way: once a reader hits one broken example, they start doubting every other example on the page, even the correct ones. Docs with no cross-linking between related topics force readers to already know the structure of your product to navigate it, which is backwards. And relying on a single format — text-only, or video-only — serves the people who like that format and loses everyone else; mixing prose, a diagram where it earns its place, and a runnable example covers more of your actual audience.
For tooling, I wouldn't overthink it: Docusaurus or ReadTheDocs for developer-facing technical docs (both free, both mature), GitBook if you want a friendlier authoring experience for tutorials and guides, and Confluence or Notion for internal wiki-style documentation where the audience is your own team rather than the public. Pick based on who's reading and how often it needs to change, not on which tool has the flashiest landing page.
Every hour a developer spends confused about your product is an hour they're not being productive, an hour closer to abandoning it, and — increasingly — an hour that turns into a public complaint somewhere. Good documentation isn't a nice-to-have bolted onto the product. It's part of the product, and it's worth being treated that way.