A Coder’s Guide to Writing API Documentation

Peter Gruenbaum

Ever been in a situation where your manager asks you to write documentation for the APIs that you developed? Let’s face it, if you’re like most developers, you love to code and hate to write. Furthermore, writing takes time away from critical tasks you need to do, such as feature development and bug fixing.
It’s no surprise that API documentation often ends up being frustrating and confusing for the reader—it rarely gets the attention it deserves.
This article is a guide on how to write API documentation. I’ll describe the most important components of API documentation and provide some suggestions about how to make it effective. I’ll also give you some hints for creating good overviews, sample code and reference material, including where you should focus your time and attention to get the best effect.

Why Document Your APIs?

Let’s start with the non-technical side of the issue. API documentation has been around ever since the first programming languages were created. There’s been plenty of time to develop effective processes for creating quality documentation, yet well-written API documentation is still quite rare. Why doesn’t it happen?
First, documentation is seldom prioritized. Even though it has a large impact on how much a software platform is adopted, the actual impact of documentation is difficult to measure. As a result, documentation is hardly ever given enough time and budget. When developers are asked to write documentation, it’s typically on top of their other responsibilities, and they must somehow fit it into their already overloaded schedule.
Second, developing code and writing documentation are two different skills. Sometimes developers are asked to write in a 
language that’s not their first language. But even if they were born in an English-speaking region and are asked to write in English, there’s a good chance that they struggled through their literature and social studies classes in school, and would’ve much rather spent that time solving problems in their math and science classes.
The first step in creating good API documentation is to ask management for the time and budget to do it well. There are two main points to make to managers:

1. Good documentation can increase the likelihood of platform adoption because it means a less-frustrating experience for developers.
2. Good documentation reduces the cost of support because developers can find the answers to their questions more easily.

Arguing the importance of good documentation may be a challenge for you if you don’t enjoy writing or if you’re completely overloaded with work, but there is an alternative. If there’s enough budget, you can hire a technical writer who will gather information from you and write the documentation.
As with developers, you’ll find technical writers with a range of experience and expertise. Many technical writers are more experienced in end-user documentation and support. For API documentation, however, you’ll want to find one who’s actually spent time as a software developer. In many companies, these types of writers have titles like programmer/writer.
Technical writers who have some coding experience under their belt understand the pain that developers go through in trying to get a software platform to work, and how good documentation can help improve the development of the platform. Also, they should have enough specialized knowledge of languages, algorithms and patterns to read your code and understand your libraries. With this knowledge and experience, technical discussion between the writer and development team will be more straightforward and productive.
That said, if the budget doesn’t allow you to bring on a technical writer, then you’ll need to write the documentation yourself. Make sure management understands that you need to carve out time to do this, just as you would for creating a new feature.

Components of API Documentation

There are four components of good API documentation:

1. Overview: Explain what advantages developers have in using the platform, and in some cases, provide an architectural description of the platform.
2. Getting started: Help the developer get started, in the form of step-by-step tutorials or simpler walkthroughs.
3. Sample code: Provide well-commented code samples that developers can build on.
4. Reference material: Provide detailed information about each class, member, function or XML element.

When developers first begin to read about an API, the first piece of information they need to know is: who would use the API and why they would use it. If the developers don’t understand this, then they’ll quickly move on to use something else. Unfortunately, this 
information often tends to be forgotten. To the people developing the API, the information is obvious—but to others, it’s not.
Come up with clear examples of when you would use the API. If you’ve got existing customers, or even potential customers, then use those as real-world examples. List the advantages of the software platform, ideally contrasting it to existing approaches. You’ll find that project managers often have this kind of information.
Overviews are also a good place to explain the API’s overall architecture. For some types of APIs (for example, many Web APIs), the API is simple enough that an architecture discussion is not necessary. However, if you’re documenting something complex, with many classes and an inheritance structure, then a full discussion of the architecture, along with accompanying diagrams, is often helpful for developers to understand it.

Getting Started

Once developers have decided to give your API a try, the first thing they’ll want to know is how to get started. In 2009, my company (SDK Bridge LLC) ran a survey on documentation, and one of the most common threads running through the responses was that developers wanted help in getting started. (See my article “Survey on SDK Documentation” at tinyurl.com/35l66yk.) This is critical for adoption: if developers find it difficult to get started, they’ll give up quickly and find another way to accomplish their goals.
A great way to get developers started is through tutorials. This approach is often much more effective than descriptive text or architectural diagrams. A tutorial leads a developer step-by-step through the process of creating a simple application that demonstrates how the API works. It often starts with non-programming activities, such as setting up your development environment or obtaining authorization credentials. Then it directs the developer to gradually add code until they can demonstrate a simple task from the API. If possible, try to structure your tutorial so that developers have something they can run and see results quickly. Then continue the tutorial, adding more features.
Chances are, you’ve worked so closely with your API that you’ve forgotten what it’s like to come at it from a completely new perspective. As you work on this section, do your best to take a step back and put yourself in the shoes of a newcomer.

Writing Sample Code

Another common thread in the SDK Bridge survey responses was the importance of good sample code. Developers learn a new platform by starting with code that they know already works, and then modifying it or adding to it. A lot, if not most, developers find it easier to learn by doing than by reading.
You probably already know how to create good production code. Good sample code shares some similarities to good production code, but there are some key differences as well. In general, good sample code should follow these guidelines:

1. Relevant information should be grouped together.
2. Clarity is more important than efficiency or robustness.
3. Simplicity is more important than a good-looking UI.

You can apply these guidelines to specific areas of software and see how sample code compares to production code.
Every programmer knows that they should never use hard-coded values in their code. Those values should be turned into constants and put somewhere that’s easy to find in case someone wants to change them.
It turns out that that’s true of production code, but not true for sample code. You should use hard-coded values in sample code in order to group all relevant information as closely together as possible. If you follow good practices for production code and define all of your constants at the top of your file, then when developers look at the line of code that uses the constant, they have to scroll to the top of the file to find out what its value is. That simple action can make them lose their train of thought. Strings, integers, hexadecimal values, and other simple values should all be hard-coded right where they’re used.
Comments are good for both production code and sample code, but in sample code they’re critical. Every class, member or function should start with at least one comment line explaining what it is or what it does. You should use comments anywhere the code is not obvious, especially if you need to document a work-around or something equally unusual. These comments can be several lines long if required. Use complete sentences and don’t be afraid to be wordy.
In general, you should have at least a line of comment for every five or 10 lines of code. However, there are some exceptions to this guideline. Code that’s extraneous to what you’re demonstrating doesn’t need so many comments (for example, UI code that’s required to display the results of your API). If you’re writing a small snippet with just a few lines of code that’s included in some reference material, you might not need comments at all. If you’re providing a very large sample that’s more like production code, then it may be more practical to lessen the number of lines of comments.
Variable, class, member and function names should be clear, regardless of whether you’re writing production code or sample code. In sample code, though, you should take this idea farther than in production code because clarity is more important than efficiency. Long, unwieldy names can be a problem in production code, but they’re usually worth it in sample code because of the added clarity. Try to make even the smallest variable name have meaning, and do not—no matter how much you’re tempted—use meaningless variable names like “foo” or one-letter names.
Object-oriented programming is one of software engineering’s best inventions. You may be surprised to learn that although it’s highly desirable for production code, it’s in fact generally not desirable for sample code. The reason is that object-oriented design distributes functionality so that data and functions are grouped together, and it uses inheritance to cut down on duplicate code. Remember, one of the fundamental principles of good sample code is that relevant information should be grouped together. Object-oriented code tends to distribute the relevant information among various classes. Therefore, developers may end up searching through an inheritance hierarchy for what a method does, which only serves to waste time and break their train of thought.
There are exceptions, of course. Some APIs require object-oriented programming to function properly. Very large samples that are more like a production application may also need object-oriented design. Just be mindful that the user wants to see all the necessary information in one class if at all possible.
A basic rule of good software design is to encapsulate functionality in functions and methods. For production code, this adds clarity and reduces duplicate code. It’s also good for sample code, because it often can create a block of code that developers can simply copy and paste into their own code, making it easy to use.
Occasionally, sample code requires a large number of lines of code that are not directly relevant to your API, but that you need in order to get your sample to run. In this case, it’s a good idea to try to encapsulate those irrelevant lines of code into a function or method so that developers can more easily ignore them.
Unless your API specifically provides UI capabilities that you need to demonstrate, you should keep the UI elements in your sample code as simple as possible. UI code can take up a lot of space and dilute the important lines of code that you want to be demonstrating. Developers aren’t concerned about whether your sample looks slick—they just want to be able to understand how your API works.
If you absolutely have to have a large number of lines of code for your UI, then package that code up into separate functions that are easy for developers to scan or ignore.
Finally, while exception handling is critical for production code to work well, in sample code it can dilute the relevant code and create a distraction. Often, a good solution is to not have exception handling, but to put in a comment indicating what kind of exceptions to handle in production code. However, there are situations where certain calls should always be made with exception handling, and in these situations, it’s worth the extra lines of code to show exactly how that exception handling should work.
Figure 1 shows an example of a function from sample code that demonstrates how to make a REST request in C# for a social networking site, returning the user IDs of the users who are connected to the specified user. In production code, the REST endpoint URL would be stored as a constant along with other relevant URLs. In sample code, however, it’s best to put this information where developers are most likely to see it and make the connection to its role in the function. Note also that error handling is suggested, but not implemented. The XML processing has been removed from this example for brevity.
Figure 1 Sample Code Example

/// 

/// Returns an array of user IDs for users that 
/// are connected to the specified user. Note that 
/// this is a simple, synchronous way to obtain the data.
/// 
/// The ID of the specified user.
/// An array of user IDs that are connected to 
/// the specified user.
 
public int[] GetConnectedUserIds(int userId) {
  // Create variable to hold the returned IDs
  int[] connectedIds;
 
  // Construct a URL using the userId and the authorization token
  string url = 
    "http://webservices.contoso.com/users/connections?userid=" + 
    userId.ToString() +
    "&token=" + 
    authorizationToken;
 
  // Create the Web request using the url
  HttpWebRequest request = 
    WebRequest.Create(url) as HttpWebRequest;
 
  // Get the response
  using (HttpWebResponse response = 
    request.GetResponse() as HttpWebResponse) {
 
    // Read the response XML
    StreamReader reader = 
      new StreamReader(response.GetResponseStream());
    string xmlResponse = reader.ReadToEnd();
 
    // Process XML to extract user IDs for connected users 
    // and responseStatus
    ...
 
    if (responseStatus != "ok") {
      // Handle errors here
      ...
    }
 
    reader.Close();
  }
 
  return connectedIds;
}

Reference Material

Reference material typically makes up the bulk of the API documentation. For each class, member, function, XML element and so on, there needs to be detailed information about what it is and how it’s used. At a minimum, reference material should cover:

• A short description
• Description of any parameters and return values
• Any important remarks that will assist the developer

If there’s more time and budget, add this information:

• Exceptions that may need to be caught
• Links to other related overview or reference topics
• A snippet of sample code, ideally from the sample code you’ve already written

Good reference documentation has a consistent style throughout. Sometimes style guidelines will exist already, but often you’re on your own to figure them out. Figure 2 lays out some general guidelines for the short descriptions.
As an example, consider the descriptions shown in Figure 3 for the Button class from the Microsoft .NET Framework. This is taken directly from the SDK documentation on MSDN.
Figure 2 Reference Documentation Style

Type	Guideline	Examples
Class	Start with a word like “Represents”	“Represents a user’s photo album.”
Methods and functions	Start with a verb	“Returns the number of contacts for the specified area.” “Pauses the video.”
Properties	Use a noun or start with verbs such as “Gets” or “Gets and sets”	“The user’s tasks.” “Gets and sets a collection of the user’s tasks.”
Events	Start with a phrase such as “Raised when” or “Occurs when”	“Raised when the response from server is received.”
XML elements	Use a noun-based phrase	“The city’s postal code.”
Boolean values	For Boolean properties, start with “Indicates whether”; for Boolean return values on methods and functions, start with “Returns whether”	“Indicates whether the control is visible.” “Returns whether two regions intersect.”

Figure 3 Reference Documentation Example

Class or Member	Type	Description
Class description	Class	Represents a Windows button control.
Button constructor	Constructor	Initializes a new instance of the Button class.
Focus	Method	Sets input focus to the control.
Visible	Property	Gets or sets a value indicating whether the control and all its child controls are displayed.
Click	Event	Occurs when the control is clicked.

Web APIs

The number of Web APIs has been growing rapidly over the past few years, and so it’s worth thinking about how Web APIs are different from local APIs. Software as a Service is becoming a popular business model, and companies are quickly finding that their larger customers want to be able use their services directly from their own systems. This means that the services provider needs to have a public API that their customers can call.
(A note on terminology: I use the term “local API” to describe the typical kind of API that existed before the Web. Technically, these APIs can be Remote Procedure Calls, therefore they’re not local; technically, Web APIs can be called on a server that’s the same computer as the client, therefore they are local. However, in most instances, Web APIs, which use standard protocols such as HTTP, are used remotely and other APIs are used locally.)
Because Web APIs are relatively new, there’s no standardization on how their documentation looks. The quality of Web API documentation varies dramatically—sometimes it’s well-organized and complete, and sometimes it’s the bare-minimum information thrown up on a wiki. If you’re going to be writing Web API documentation, it’s worth spending some time looking at how various companies have documented their APIs so that you can find a good template to follow. For example, Twilio, a platform for voice and messaging applications, has an excellent example of REST documentation, which can be found at twilio.com/docs. Hopefully, over time, the industry will settle into a small number of effective templates.
In some ways, Web API documentation is more critical than local API documentation because it can be more difficult for developers to experiment with Web APIs in order to figure out how they work. Developers may have limitations (quotas) on how many times they can make a call, or their experimentation may be affecting a live system, or it may be difficult to emulate specific conditions, such as when the server is under heavy use.
As mentioned earlier, developers rely heavily on sample code. One of the powerful things about Web APIs is that they’re independent of platform and language. Unfortunately, this means extra work when creating sample code. You may find yourself writing sample code in Python, Ruby, Java, C# and so on. Try to find out what your customers use most and focus on the languages that are most important to them.
The two most common technologies for Web APIs are SOAP and REST. SOAP has a definition format (Web Services Description Language, or WSDL) that’s a great starting point for reference documentation, whereas REST does not. Sample HTTP calls and XML/JSON files are useful for both of these technologies in illustrating how they work, but they’re not sufficient. Samples should be followed by tables that describe each element as well as its data format.
For example, it may not be enough to describe a parameter as a string. Are there special characters it can’t handle? Are there limitations on its length? If an XML element is a date, you should specify the format of the date. If it’s a time, then you need to specify its time zone.
Also, you’ll need to explain how errors are handled. This may vary for the different formats that your API supports. If your API uses HTTP response codes to flag errors, these should be documented. Error documentation should explain why an error occurs and how to fix the problem.
Authentication is often required for Web APIs, and this needs to be documented in detail as well. If developers need API keys, be sure to give them step-by-step instructions on how to obtain these. Also, don’t forget that Web APIs are built on top of HTTP, which is an incredibly rich protocol. You may have HTTP-related information that requires documentation, such as caching, content type and status codes.
Web APIs are new enough that we’re still in a period of figuring out the best way to document them. Expect to see standardization in the next few years.

Publishing

So far I’ve been focusing on content, but you’ll also need to publish the documentation so that developers can read it. In general, developers expect to see Web-based, hyper-linked documentation rather than flat files such as a PDF. There are several ways to get your documentation on the Web.
If your API is small, it may be simplest just to create HTML files. Use CSS to get the look-and-feel to match your company’s Web site.
Wikis provide a structure for more-complex APIs. Wikis also allow you to easily update or add to documentation over time without needing access to other tools or servers. In addition, the group collaboration aspects of wikis enable entire teams—even your users—to contribute. However, slapping together a wiki and hoping your developers and users will write the docs isn’t a very viable API documentation strategy.
Several free, open source wiki engines are available and are becoming popular for API documentation, such as the PHP-based MediaWiki (mediawiki.org/wiki/MediaWiki) and the PERL-based TWiki (twiki.org).
Commercial documentation tools such as Madcap Flare (see madcapsoftware.com/products/flare) and Adobe RoboHelp (see adobe.com/products/robohelp) are designed primarily for end-user documentation, but can be easily adopted for API documentation. They provide a simple UI for entering in information and give you a more polished look than a wiki. They can generate both Web and flat-file documentation from the same source.
Online collaboration services, such as PBworks (pbworks.com) and MindTouch (mindtouch.com), are also being used for API documentation. In addition to the collaborative features of wikis, these offer additional features, such as hosting, fine-grained access control and scripting capabilities. These services typically require a subscription fee for commercial use.

Ship It!

Good API documentation is critical for getting your platform adopted and for cutting down on the number of support calls your company receives. If you can convince your manager to hire a technical writer with the right skills, then do it. But if you can’t, follow the guidelines in this article.
Your documentation should have an overview, help on getting started, sample code and reference material. In the overview, be sure to explain why your platform should be used. Put together tutorials to help developers get started. The sample code should focus on clarity and simplicity, and it won’t always follow the same coding principles as production code. Your reference material should be detailed and consistent. There are a number of tools available to get your documentation published on the Web.
Now get writing!

---

Peter Gruenbaum  started out as a physicist but became a software developer, working on technologies as diverse as Tablet PCs, Augmented Reality, computer-aided design and surgical simulation. He founded SDK Bridge LLC to bring together his love of technology and writing, where he writes and teaches about technology.
Thanks to the following technical experts for reviewing this article: John Musser (ProgrammableWeb) andEugene Osovetsky(WebServius)