Ok, actually I don't think the documentation needs to be improved a lot, I think you can get 1000% better if you add a "quick start" guide for developers. Just a small page with examples so they get the feel of it. Then they can consult the full reference if they need do to anything else.

For example, https://strike.acinq.co/documentation/get-started and https://developers.trello.com/docs/api-introduction