Documentation is where adoption is won or lost, and I have believed that since the first thing I wrote in 2010. A fairly ordinary API with exceptional documentation outperforms a better API with poor documentation every time.
The minimum viable set: a getting-started guide that takes someone from landing to a successful call
with the fewest possible steps; authentication explained with a working example for each supported
method; interactive reference documentation generated from your OpenAPI so it can never disagree with
the contract; real examples for every operation, with realistic values rather than string; complete
error documentation including what each error means and what to do about it; and a change log.
Beyond the minimum, the things that make a real difference: task-oriented guides organized around what people are trying to accomplish rather than around your endpoints; a runnable collection so somebody can fork and go; documented rate limits and pagination behavior; and a sandbox or test credentials.
The failure mode to avoid is treating generated reference as the whole of documentation. Reference answers “what does this endpoint do.” It never answers “how do I accomplish the thing I came here for,” and that second question is why people are on your site.
