Docs are a product, not an afterthought

You can learn most of what you need to know about how a company sees its developers by asking one question: who owns the docs? When the answer is "uh, whoever's got a spare afternoon," you already know they're bad. They always are.

Here's why that matters more than teams think. Documentation is the one thing a developer reads while they're still deciding whether to trust you at all. It's the sales call, the demo and the onboarding rolled together, except nobody's on the call and the demo is running in their own terminal. Get it right and it works for you around the clock. Get it wrong and it turns people away just as reliably — you just never find out, because they leave without a word.

What docs are actually for

One job: get somebody from "huh, maybe" to "oh, it works" as fast as you possibly can. Every sentence is either moving them toward that moment or standing in the way of it. When we edit a set of docs, that's more or less the only question we're asking of each line.

The stuff we check

• A quickstart that ends in a result, not a tour. Five minutes, and something visibly happens on their screen.
• Every snippet actually runs — we put them in CI. A code sample that errors on line one does more damage than no sample at all.
• Say why, not just how. Reference docs tell you what a function does. Good docs tell you when you'd reach for it, and when you wouldn't.
• Show things breaking. Errors, edge cases, the gotcha someone hits at 11pm and googles in a mild panic. That page gets more traffic than your landing page. Bet on it.
• Make it skimmable. Developers don't read top to bottom. They scan, grab the line they need, and bounce. Write for the scanner.
• Put a date on it. Stale docs are worse than none, because now people can't trust the pages that are still right.

Docs tell you where the product hurts

This is the part people miss. Every place the writing gets awkward — "first set this flag, then ignore the warning that pops up" — is a place the product is asking too much of somebody. Whoever writes your docs quietly becomes your most honest product reviewer, because they can't paper over the rough edges the way a polished feature page can.

Give them an owner

A roadmap. A name attached to them. Analytics on which pages people bail from. Some reason to revisit them that isn't "a customer complained in public." The moment docs get a product manager's attention instead of an engineer's leftover Friday, they stop being a cost you tolerate and turn into the best channel you've got.