Developer docs are the one place robotic AI writing costs you users. A new engineer lands on your API reference, hits three paragraphs of "seamlessly empowers developers to unlock robust workflows," and leaves for a competitor whose docs just work. Here's how to keep AI-written docs human.
The tells in generated docs
- Concept before command. Nobody reads the philosophy section before they want the endpoint. Lead with the snippet.
- Adjective stacking. "Powerful, flexible, modern" is four words for zero information. A fact ("returns JSON in under 40ms") beats three adjectives.
- No failure modes. Generated docs tell you it's great. Real docs tell you what breaks behind a proxy or on an older SDK.
The 3-pass fix
- Lead with the verb. First line: what this does and who it's for, in one sentence. Then the code block. Everything else below the fold.
- Cut 30% of the adjectives. Then cut the survivors that aren't measurable.
- Add one real gotcha. A version constraint, a "won't work on Safari" note, a rate-limit detail. Specifics are the cheapest proof a human shipped this.
Paste your doc intro into a free AI-risk scorer before you publish: https://humanizeai-lab.pages.dev/tools/ai-risk-scorer.html — I keep public-facing docs under 40%. The fixed prompt set I run reference, changelog, and PR descriptions through is here: https://felovery.gumroad.com (code FIRST50 = half off, no expiry).
Good docs aren't longer. They're less padded.
What's the doc you wish the last library you used had written?
Top comments (0)