Standardizing API documentation

The market for application programming interfaces (API) is growing rapidly and software vendors are expanding their offerings of development platforms, tools and APIs. Professional API documentation plays a key role in the adoption of these offerings. The recently published book Standards and Guidelines for API Documentation by Anne Tarnoruder is a valuable source for both technical writers and developers producing API documentation.

Text by Anne Tarnoruder


Standardizing API documentation

Image: © mnbb/

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, leading to lower quality in the documentation. Professional technical writers, on the other hand, do not always have the special knowledge and skills required for these topics.

To address these gaps, SAP formed a group of API documentation experts in 2014 to produce a company-wide set of standards, guidelines and best practices. The team was led by myself. These Standards and Guidelines (S&G) aim to reach a higher level of quality and usability in the APIs published by the company, and thus increase customer satisfaction and ...