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