I should not need to read a novel to call your endpoint.
If your API documentation spans forty pages, multiple guides, a getting started tutorial, a concepts section, a best practices section, and a troubleshooting FAQ, your API is not well documented. Your API is badly designed. The documentation is compensating for failures that should have been fixed in the API itself.
Good APIs are self-evident. You look at the endpoint, you understand what it does. You look at the request, you understand what to send. You look at the response, you understand what you got back. The documentation exists to confirm what you already intuited, not to explain an incomprehensible system.
Stripe gets it right
Stripe is the gold standard here and it is not close. Their API does what you expect. Create a customer, charge a card, handle a subscription. The endpoints are named sensibly. The parameters are named sensibly. The responses are predictable.
Yes, Stripe has extensive documentation. But you do not need to read it all to get started. You can look at one endpoint, understand the pattern, and apply it everywhere. The complexity in Stripe’s docs comes from the complexity of payments, not from the complexity of their API design.
Compare this to APIs where you need to read three guides before you can make your first request. Where the authentication flow requires a flowchart. Where the same concept has different names in different endpoints. Where the response structure changes based on parameters you did not know existed.
The difference is design. Stripe spent time making their API intuitive. Other companies spent time documenting their unintuitive API.
Documentation is not a substitute for design
When I see massive docs, I see a team that gave up on making the API simple and instead wrote words to explain the complexity. This is backwards. Every page of documentation is an admission that the API failed to communicate something on its own.
Authentication should not need a guide. If your auth is so complicated that developers need a walkthrough, simplify your auth. Error handling should not need a section. If your errors are so cryptic that developers need a decoder ring, write better errors. Pagination should not need an explainer. Pick a standard approach and use it consistently.
The best APIs I have used have almost no docs. A few examples, a reference page, done. You call the endpoint, it works, you move on with your life. The API did the work so the documentation did not have to.
Concepts sections are a red flag
If your docs have a section called Concepts or Understanding Our Model or How Things Work, something has gone wrong. You have built a system that requires education before use. That education cost falls on every single developer who integrates with you.
I do not want to understand your model. I want to send a request and get a response. I want your weird internal abstraction to be hidden behind a sensible interface. If I need to understand that a Widget contains Sprockets which reference Gizmos through a Contraption in order to make a simple API call, you have leaked your implementation details into your interface.
Abstract it better. Name things better. Flatten the hierarchy. Do whatever you need to do so that developers can be productive without a computer science degree in your specific domain model.
The onboarding gauntlet
Some APIs cannot even be called without completing an obstacle course. Get an API key (separate system). Configure webhook endpoints (another page). Set up authentication tokens (yet another guide). Enable specific scopes (buried in settings). Handle OAuth flows (forty-five minute tutorial). Only then can you make your first request.
By the time a developer gets through all this, they have invested hours without accomplishing anything. Some will give up. Others will push through but resent your product. Nobody finishes that gauntlet thinking wow, what a pleasant developer experience.
Make the first request easy. Let people get a response in minutes. Handle the complicated stuff later, progressively, as they need it. Front-loading complexity guarantees drop-off.
Write less docs, design better APIs
Here is my controversial take: most documentation effort is wasted. Teams spend weeks writing guides that developers skim once and never reference again. They maintain docs alongside code, a constant tax on every change. They build elaborate docs sites with search and versioning and feedback widgets.
That effort would be better spent on the API itself. User test the endpoint names. Simplify the request structure. Improve the error messages. Make the responses consistent. Do the hard design work that makes documentation almost unnecessary.
The best documentation is the API itself. Everything else is overhead.
If you are about to write a forty-page docs site, stop. Ask why developers need forty pages. Then fix that instead.