Why API Providers Must Offer Solid API Documentation

While API analytics can provide quantifiable, actionable information, the associated API documentation is often neglected by developers as a secondary consideration. In a recent post on the APImetrics blog, Ian Watson discussed this point, and ways to improve documentation standards.

Quality documentation should be viewed as much a part of the product as the API itself, and selling a product well involves knowing your audience. Whether that audience is a manic debugger, a brain-storming product manager or a fresh dev straight out of coding bootcamp, documentation is key to wider adoption so keeping these users updated and supported is imperative.

Documentation is the tool that defines where the problems may lie, what the product’s capabilities are, or simply state foundational processes in a clear way. Whatever the scenario, a lack of reference material may lead potential users to look elsewhere. Thankfully, the task of writing documentation is no longer as manual as it used to be since automated API documentation frameworks have emerged.

Products like Swagger, API Blueprint and RAML offer various methods for automatically creating documentation for every stage of your API life cycle. With the access and ease-of-use that tools like these provide, it is easier than ever to provide your users with comprehensive support.

Unfortunately, creating documentation is not enough. Keeping this work up-to-date is just as important since poor or obsolete documentation frustrates developers who may decide to try a different provider. APIs change regularly as bugs are fixed and new features added, so be sure to communicate changes to those who depend on your product. The rise of the API economy is supported by its documentation, so make sure yours is built on a solid foundation.

Be sure to read the next API Management article: How NZ Post Relies On APIs To Fend Off The Threat From Uber, Others

Original Article

API Documentation Needs Love too




Google Apps Script functions fail here.

I was recently working on extracting Google Calendar appointments into a Google Sheets spreadsheet for formatting and "printing" to a PDF documents and emailing to members of our club.

I wanted to provide a way for the Secretary to select the range of dates to export. Google provided lots of examples, but they were for the old and deprecated way of doing it, not for the new HTML Service.

Google had given months of notice that the old methods would be deprecated, so I was very disappointed that equivalent examples had not been prepared in time for the new methods.

If you want to see more details, here's my comment on Google+: