If Your API Needs a 40-Page Docs Site, Your API Is Bad
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.