The Business Case for Excellent API Documentation

If your company is selling web services that are accessed by through APIs, one of the most important factors for your ability to attract paying customers is your API documentation. Management teams from potential customers will be interested in what information your APIs provide, their capacity and reliability, and how quickly they can scale.

Once your product has passed the test in all these areas, your potential customer’s development team will be brought in to assess your APIs from the point of view of performance and ease of integration into the customer’s planned service. Here is where poor API documentation could make the difference between a sale and your potential customer walking away to another vendor.

If the customer’s developers express concerns about the difficulty of integrating your API, or if they quickly come up with questions that your API documentation doesn’t address, your product might appear (even if unjustly) to require high maintenance–which could also raise questions (fair or not) about reliability.

The documentation you provide with your APIs is key in the decision-making of any potential customer, because the cost of using your APIs includes not only your fees, but also the cost of the effort your APIs impose on the customer’s development team.

Let’s put the shoe on the other foot: assume you have a product that requires weather information, and you’re searching for a third-party API to provide you with that. To start your search, you might read, for example, Top 5 Best Free Weather APIs. This article highlights five weather APIs selected out of 25 APIs that were studied.

If you follow the links to the individual weather APIs, you find lesser and greater amounts of documentation, some better organized than others, some with illustrative examples, some without, etc. This documentation, for better or worse, is the “User Manual” your developer team will refer to in order to integrate the weather API into your product. Ideally, everything’s there, and your developers don’t have to constantly communicate with the third party API team in order to implement the integration. If that’s not the case, then everybody’s in trouble.

Daniele Procida states it well in the introduction to his article What nobody tells you about documentation:

It doesn’t matter how good your software is, because if the documentation is not good enough, people will not use it.

Even if for some reason they have to use it because they have no choice, without good documentation, they won’t use it effectively or the way you’d like them to.

If they have to try to use it without good documentation, that’s going to damage your company’s reputation: you’ll have created a dissatisfied customer who dissuades others from using your product, rather than having a satisfied customer who freely advertises your product to colleagues at other companies or departments.

Daniele proceeds to describe the right way create documentation that well serves the needs of your customer’s development team. The article describes four fundamental types of documentation, their purpose and characteristics:

  • Tutorials: learning-oriented lessons for beginners
  • How-To Guides: goal-oriented guides that show how to solve specific problems in a series of steps
  • Explanation: understanding-oriented descriptions of background and context
  • Reference: information-oriented accurate and complete descriptions

For more details, read the full article. You can also watch Daniele’s presentation at PyCon Australia 2017.

–Kevin Farnham