Written by Peter Gruenbaum
API documentation is a fast-growing segment of technical writing. API stands for Application Programming Interface, and it’s the way that software systems communicate with each other. What sets it apart from other types of documentation is that you are writing for an audience of software developers. APIs provide certain functionality, and software developers need to understand how the APIs work in order to build applications that use them.
There are several types of APIs, including programming APIs, web APIs, and hardware APIs. This article will discuss the two most common types, which are programming and web APIs.
Do you need to know how to write code in order to document APIs? There isn’t a simple answer to that question. For some types of APIs, you should know programming fairly well. For other types, it may not be required, but it is often useful.
A programming API (also called a “client library” or SDK, for Software Development Kit) is a set of software functionality that runs on a device, such as a smartphone, tablet, desktop, or server. For example, a software developer creating an iPhone app would use the iOS SDK. Let’s say that a developer wanted to be able to pop up a window that asked a question and prompted the user to tap “OK” or “Cancel”. API documentation tells the developer what code is required to do that action. It may involve several steps, such as first creating the dialog, then displaying it, and then reacting to the choice that the user made. The developer needs to know how to specify the message, how to specify what buttons to display, and how to find out what button the user tapped.
API documentation writers definitely need to understand some level of programming in order to document programming APIs, but how much you need to know will vary. The documentation for the iOS example I gave above (UIAlertController) requires a great deal of knowledge about iOS programming in order to understand it. However, many programming APIs are a lot simpler, and require only that you have a good understanding of object-oriented programming languages like Java. If you write documentation without having that solid understanding, then you may write something that is not completely accurate, and developers will no longer trust the documentation.
A web API defines the communication between a client device and a server over the web. Web APIs are a relatively new phenomenon in the software industry, but several recent technology trends (mobile devices, the internet of things, and big data) have made them extremely popular. The site ProgrammableWeb contains a directory of publicly-available web APIs, and they analyze the data and look for trends. As you can see in the graph below, the number of these APIs have grown exponentially. And these are just the public APIs — people in the industry say that there are 10 times more web APIs that are available only internally or to partners.
What API Documentation Should Cover
Like any kind of technical writing, API documentation needs to provide both overview material to orient the reader, and reference material to provide specific information on how to accomplish tasks. Here are sections that are common in API documentation:
• Overview — what the API does and why you should use it
• Getting Started — a short series of steps to quickly get to the first use of the API
• Architecture — for programming APIs, how the various pieces fit together
• Authentication — for web APIs, how security is handled
• Tutorials — step-by-step instructions that leads the reader through how to accomplish common tasks
• Reference — detailed information on what each piece of the API does
How to Learn More
Several resources are available to learn more about API documentation. They include:
• STC webinars by Sarah Maddox, Ed Marshall, Joe Malin, and others
• Workshops by Marshall Documentation Consulting
• Online courses by SDK Bridge