Bad documentation doesn't just frustrate developers—it costs you money. Every confusing paragraph is a support ticket. Every missing example is a delayed integration. Every broken code sample is a developer who gives up and looks at your competitor.
After years of working with API documentation across healthcare, fintech, and enterprise SaaS, I've seen the same patterns emerge again and again. Here are the eight most common anti-patterns—and what to do about them.
The Wall of Text
Dense paragraphs with no code examples, no visual breaks, and no clear hierarchy. Developers scan docs—they don't read novels.
Symptoms
- •Paragraphs longer than 3-4 sentences
- •No code snippets for first 5+ screens
- •Missing headers and subheaders
- •No bullet points or numbered lists
The Fix
Break content into scannable chunks. Lead with code examples. Use headers liberally. If you can't skim it in 30 seconds, rewrite it.
The Authentication Mystery
Your auth setup is buried three clicks deep, assumes prior knowledge, or worse—doesn't show a complete working example.
Symptoms
- •Auth docs don't include a copy-paste curl command
- •No mention of auth until the 'API Reference' section
- •Token format not clearly explained
- •Missing info on token expiration and refresh
The Fix
Put authentication front and center. Show a complete request with auth headers. Explain the token format. Cover edge cases like expiration.
The Error Code Graveyard
Either no error documentation at all, or a table of codes with no context on what causes them or how to fix them.
Symptoms
- •Error codes listed without explanations
- •No troubleshooting guidance
- •Generic error messages in examples
- •Missing HTTP status code documentation
The Fix
Document every error code with: what triggers it, what the developer did wrong, and exactly how to fix it. Include the error response body.
The Outdated SDK
Your SDK examples reference deprecated methods, old library versions, or patterns that haven't worked in years.
Symptoms
- •Package versions in examples are 2+ major versions behind
- •Code examples that throw deprecation warnings
- •Screenshots of old UI for dashboard/console
- •Links to documentation that 404
The Fix
Audit your examples quarterly. Automate testing of code samples. Version your docs alongside your API. Remove or clearly label deprecated content.
The Copy-Paste Failure
Code examples that don't actually work when copied. Missing imports, undefined variables, or incomplete snippets.
Symptoms
- •Examples missing import/require statements
- •Placeholder values that aren't clearly marked
- •Incomplete error handling
- •Code that only works with unstated prerequisites
The Fix
Every code example should be copy-paste ready. Test them. Mark placeholders clearly with YOUR_API_KEY style formatting. Include all necessary imports.
The Language Lottery
Examples only in one language (usually curl or one SDK), leaving developers using other stacks to figure it out themselves.
Symptoms
- •Only curl examples for a REST API
- •SDKs without code examples
- •No JavaScript examples for a web-focused API
- •Python-only examples for a general-purpose API
The Fix
At minimum: curl, JavaScript/TypeScript, Python. Ideally: add Go, Ruby, PHP, Java for enterprise. Use tabs to organize language options.
The Versioning Void
No clear indication of which API version the docs apply to, or what changed between versions.
Symptoms
- •No version number visible in docs
- •Changelog is empty or years out of date
- •Breaking changes not documented
- •Multiple conflicting examples for same endpoint
The Fix
Show the current version prominently. Maintain a changelog. Document breaking changes clearly. Allow viewing docs for older versions.
The Dead End
Documentation that explains what an endpoint does but not why you'd use it or what to do next.
Symptoms
- •No 'Getting Started' guide
- •Endpoints documented in isolation
- •No common use case examples
- •No 'Next Steps' or related endpoints sections
The Fix
Create user journey-based guides. Link related endpoints. Add 'Common Use Cases' sections. Always answer: what would the developer do next?
The Good News
Every one of these anti-patterns is fixable. And fixing them doesn't require a complete rewrite—often, focused improvements to your auth docs, error handling, and code examples can dramatically improve the developer experience.
The companies with the best documentation—Stripe, Twilio, Plaid—didn't get there by accident. They invested deliberately in developer experience because they understood that great docs are a competitive advantage.
Your docs can get there too.
Recognize Your Docs Here?
Book a free audit call and I'll show you exactly which anti-patterns are hurting your API adoption—and how to fix them.