January 2019
Text by Anne Tarnoruder

Image: mnbb/istockphoto.com

Anne Tarnoruder is an experienced technical communicator with a strong background in software engineering. Leveraging her background, Anne focuses on documentation for developers, APIs and SDKs. She is a frequent speaker at professional conferences on API-related topics.  


www.linkedin.com/in/annetarnoruder


 

Order your copy of Standards and Guidelines for API Documentation at info[at]tekom.de


Softcover: 70


eBook (PDF): 55

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.

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 acceptance of APIs.

The S&G have since been used across SAP as a source of guidance and education for both writers and developers producing 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. The 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. The Standards and Guidelines for API Documentation are published by tekom Europe and available in print or as an eBook.

Here is a brief summary of what you will find in our book.

Background information, terms and concepts

For those technical writers who are new to or not very familiar with the subject of APIs, the S&G provide some background information and introduce the main concepts and terminology of APIs and API documentation in a short glossary.

An API package provided by a vendor will typically include the following documentation deliverables:

API reference 

Contains structured reference information about all the elements of APIs. An API reference can either be auto-generated from API descriptions (documentation comments written in source code or in separate files of a special format) or written manually in free style or using a template. API descriptions for auto-generation are usually written by developers in or close to source code.

Developer guide

Contains all the information required to use the APIs, such as:

 

  • Setup and access information.
  • Concepts, subject domain background, architecture, workflows, diagrams.
  • Tutorials, how-to's, code samples illustrating various use cases.

Developer guides are usually written by technical writers in a documentation system.

In addition to these official deliverables, API vendors provide less formal community content, such as blogs, videos, forum posts, articles, etc. via developer portals and/or social media.

Roles and responsibilities

API documentation is a joint venture of developers and technical writers, so their effective collaboration is crucial for the quality and usability of the APIs. To make sure that each role contributes to the completeness, clarity, consistency and overall professional look and feel of the API documentation, an organization needs to integrate best practices of this collaboration into its development processes.

The S&G define the responsibilities of each role in the process, and suggest certain best collaboration practices, such as reviewing API naming and descriptions by tech writers early in an API development cycle to eliminate the need to fix the naming after the APIs are released.

The S&G don't define any specific tools to use in these processes. An API review can be performed in any format that is convenient for both technical writers and developers, and is available in their work environment. They can use a code review tool such as Gerrit, or work on source code files or on generated output.

By the same token, developer guide topics written by a technical writer need to be reviewed by a developer or architect to ensure their technical accuracy and consistency with the reference information.

API naming guidelines

Names are the user interface of APIs. Meaningful, clear, and self-explanatory naming is a key factor in API's usability and adoption.

Even though API names are in most cases defined by developers and architects, technical writers should be involved to make sure that these names are:

 

  • Written in professional and correct English.
  • Using correct terminology.
  • Consistent, meaningful, and unambiguous.
  • Compliant with the industry-wide naming conventions for the relevant language or technology.

API names aim to convey the meaning of each API element and follow the function and variable naming conventions for programming languages. The S&G elaborate on these conventions and the naming conventions for REST/OData resources as well as on the most common API naming mistakes such as:

 

  • Very long names
  • Names with grammar errors
  • Ambiguous names and abbreviations
  • Embedded product names
  • Names that explain implementation
  • Names that mismatch descriptions
  • Names with acronyms
  • Names with redundancies

       These mistakes are explained in detail and illustrated by good and bad examples.

Documenting REST/ODATA APIs with the OpenAPI specification

REST (Representational State Transfer) APIs, also known as RESTful Web services, are cross-platform APIs that perform CRUD (Create, Read, Update, Delete) operations on data resources using the standard HTTP calls over the Web.

The Open Data Protocol (OData) is a standard protocol for interacting with data via RESTful interfaces. An OData service is an implementation of the OData protocol that exposes data to client applications, which can perform CRUD operations on the data using REST API calls.

The most effective way to produce and maintain REST/OData API reference documentation is to auto-generate it from comments or annotations in source code or from the definition files of a special format.

There are several API definition protocols currently used in the software industry, such as RAML, API Blueprint, and OpenAPI Specification (OAS, f.k.a. Swagger).

The OAS and Swagger tools are widely recognized as the most popular open source framework for defining and documenting REST APIs. An API definition written according to the OAS in JSON or YAML format describes all the elements of an API.

The OAS supports verbal descriptions for most API elements, such as operations, parameters, responses, error and status codes, security parameters, and more.

Usually, API definition files are written and maintained by developers together with the code, but technical writers should review the descriptions to ensure their quality.

The S&G provide comprehensive guidelines for writing the descriptions of API elements in the definition files, illustrated by examples.

API definition files are used as a source for automatic generation of interactive HTML documentation by Swagger or similar tools.

If for some reason auto-generation is not an option, you can document REST and OData APIs manually using the dedicated structured templates included in the S&G.

Documenting Java, JS, .NET and C/C++ APIs

API reference documentation for these languages can be auto-generated by tools such as Javadoc, JSDoc and Doxygen from documentation comments that are written in source code according to certain syntax and formatting rules.

The S&G include comprehensive writing guidelines for documentation comments, descriptions and tags, accompanied by examples. These guidelines are derived from well-known sources such as the Javadoc writing guidelines by Oracle Technology Network, JSDoc Tag Dictionary, and MSDN library for Microsoft Visual Studio.

These guidelines are complemented with sample Javadoc templates for packages, interfaces, classes, methods and more.

Writing helpful developer guides

Developer guides differ in various parameters, such as platform, technology, product, scope, size and more, so there is no one-fits-all standard. This section suggests how to make your developer guides clear, concise, helpful, and pleasant to use.

A typical developer guide:

 

  • Complements API reference documentation by explaining how to set up and use APIs (and/or services, SDK, development platform).
  • Contains conceptual, setup, quick start and how-to information.
  • Does not contain implementation details irrelevant to users.
  • Is created and maintained by technical writers in the documentation systems.
  • Is written in free style.
  • Is delivered as part of product documentation.
  • Provides effective navigation and search capabilities.
  • Includes an integrated or easily accessible API reference.

Various usability studies show that API documentation users differ in their learning preferences:

 

  • Those with a top-bottom approach would first read all the conceptual topics, and only then start trying the API calls.
  • Those who prefer a bottom-up approach would delve right into code samples to get a quick hands-on experience with the APIs.

Thus, a good developer guide should accommodate both approaches, and help all users to easily find what they need most.