3 ms·
One of the most important and easy ways to avoid frustrating API docs is to check them periodically to make sure nothing is out of date. Last year I started us
by the_bear 15y ago
One of the most important and easy ways to avoid frustrating API docs is to check them periodically to make sure nothing is out of date.
Last year I started using Amazon's Flexible Payment Service (FPS) and their docs were so out of date that they linked me to a PHP library that was over three years old and already deprecated. I spent weeks getting my billing system working and then as soon as it went live I got an email from Amazon telling me that I was using a deprecated library that was being phased out in the next few months.
I also had the same experience with Twilio, although luckily with them the old library didn't work at all so I didn't waste time developing with it.
Updating basic things like links to helper libraries can save your customers countless hours of headaches and frustration.
- jsankey 15y agoFor this reason I would say you need to automate as much as possible. Maintaining quality documentation is expensive, and although much of it requires a human eye there should be plenty of opportunity for machie verification too. For instance, code examples (snippets or sample projects) should be actually compiled and tested, automatically, every time the docs or the API itself changes. Think of it as CI for your documentation.
- johns 15y agoI'm sorry you ran into the issue with Twilio. I'm in the position now where I can find and fix all of these issues so hopefully you won't see that happen again. If you email me your shirt size and address, I'll try to make it up to you. jsheehan@twilio.com