An API with poor documentation is hard to use, however well it is built. Good documentation saves support time and wins the trust of the people who connect to you.
The essentials
Include what a new developer needs on day one.
- How to get access and a test account
- Every request, with a working example
- What each response and error means
- The limits on requests and sizes
- A changelog of updates
Write for the reader
Start with a short guide to the first successful request. People forgive missing detail much sooner than a confusing start.
Keep it true
Documentation that does not match the real API is worse than none. Update it as part of every change.