[dmlittle]

At the end of the day content accuracy is _a lot_ more important than content layout. There is nothing more frustrating than trying to follow the guidelines of an API Documentation and not being able to make the request you want.

My suggestions would be the following: 1) Make sure the API docs are up to date! 2) For each API route, mention all possible fields as well as their type and maybe a short description of what they do if it's not obvious. 3) If you're providing wrappers, show an example of how to use them with each endpoint.

If you make sure you're doing 1 & 2, your documentation will be helpful and easy to use. I work for an API company and we've made sure that our API is always up-to-date by automating it. If we ever add, remove or rename a certain parameter in a new API version, the documentation will reflect those changes as soon as they go live without us have to update the documentation manually. This has proven to be highly effective as it guarantees our docs are always right and up-to-date.