Challenges of API Documentation from a Provider Perspective and Best Practices for Examples in Public Web API Documentation

Abstract

Developers frequently have to learn new Web APIs provided by other teams or organizations. Documentation, especially code examples, supports learning and influences the consumers’ perception of an API. Nevertheless, documentation repeatedly fails to address consumers’ information needs. Therefore, we identify four major challenges of creating and maintaining public Web API documentation from a provider perspective which are unknown customer needs, the difficulty of balancing the coverage of varying information needs and keeping documentation concise, the high effort of creating and maintaining documentation, and missing internal guidance and governance for creating API documentation. In addition, we derive 46 best practices candidates for code examples as part of Web API documentation from literature and 13 expert interviews. Moreover, we evaluate a subset of eight of these candidates in the context of the Web API documentation for a public GraphQL API in a case study with 12 participants. As a result, we validate the analyzed eight best practices candidates to be best practices for public Web API documentation.