[onion2k]

Very true, but it needs to be a specific type of documentation - namely something that explains how to use the API rather than what the API endpoints are. By sitting down and writing about what's needed to get the most out of the API, as well as writing extensive code examples, you're forced to think about how people are going to use the API. Any problems, quirks or bugs should be obvious at that point because you're using the API as it'll be used by other developers. Simply listing the endpoints with what parameters they need and things they'll return won't make your API better.