As a writer who works on API (Application Programming Interfaces) quite a bit, I have heard quite a few API documentation myths that I believe stand in the way of having good API documentation. Documentation that really helps the users both use and LEARN how to use the API. Historically, a lot of API documentation was merely a technical reference (and often a poorly written or incorrect/incomplete technical reference). If you already know the API or the system the API interfaces with, you will have fewer issues with this poor API documentation, but if you are new to programming, the API, or the interface system, the documentation can make all the difference between success and failure — or at least a lot of frustration.
One of the biggest hurdles to developing comprehensive and rich API documentation is overcoming some of these prevalent API documentation myths. My goal when working on a project is to never to have my documentation be judged just “okay”, but rather to have every person who uses my API documentation find the API so easy to learn and use that they tell all their friends.
Most API documentation myths seem to originate from a few root preconceptions and learned prejudices:
- Only seasoned developers use APIs.
- All users are familiar with the system the APIs reference, including back-end terminology and assumptions.
- Crowd-sourced or user-provided information is correct and complete.
Here are some samples of API myths that frequently come up. I’m always interested in hearing the ones you have heard as well. Feel free to comment or use the contact form to let me know:
- Our API is so easy, it doesn’t need documentation.
- Our users are professionals, they don’t need documentation.
- Our API doesn’t need any documentation since it’s only for internal use.
- Our users can do the documentation for us.
- Our developers/testers/pms can can write the API docs.
- Our schedule has no time in it for API documentation.
- Our documentation can be crowdsourced in a wiki.
In upcoming posts, I’ll address each of these myths and any others that come to mind in the meantime.