Standards and Guidelines for API Documentation

In the rapidly expanding API economy, software vendors are expanding their offerings of development platforms, tools and APIs. Professional API documentation is a key facilitating factor in the adoption of these offerings. Various companies and tool vendors define and maintain their own rules and best practices for documenting APIs, but so far there is no comprehensive widely adopted industry standard in this area. Furthermore, API documentation tends to fall between the cracks. It is often written by developers who don't have enough resources and professional writing skills, which leads to the lower quality of documentation. On the other hand, professional technical writers do not always have the special knowledge and skills required to handle these topics. To address these gaps, a group of API documentation experts at SAP, led by Anne Tarnoruder, had been formed in 2014 to produce a company-wide set of standards, guidelines and best practices. These Standards and Guidelines (S&G) aim to reach a higher level of quality and usability of the APIs published by the company, and thus increase the customer satisfaction and acceptance of APIs. The S&G have since been used across SAP as a source of guidance and education for both writers and developers who produce API documentation. The S&G cover both auto-generated and manually written API reference documentation, and apply to the major API languages and technologies, such as Java, JavaScript, MS.Net, REST and OData. Though originally written for SAP, these guidelines, based on the widely used industry standards for these languages and technologies, are more of a generic nature than specific to SAP and can be applied in any company.