So You Want to Document APIs …

1949 Meteor by dave_7-on-flickr.com - document APIs

Image by Dave 7, Flickr, No Changes, License

It’s hard to keep track of how many times APIs (Application Programming Interface) shape our experiences per day, or even per hour. Although you experience an API when your PayPal transaction goes through, or your Uber ride picks you up, an API itself is intangible, more so than typical end user software. Even embedding a YouTube video in a WordPress blog post counts as using an API. With hundreds of thousands of publicly-facing APIs that are available to an ever-wider user base, companies are under great pressure to make their APIs easy to use and useful. It should be no surprise that the growth in API documentation job postings is enormous—it reflects a hot market for technical writers who specialize in API documentation.

You see Google Maps just about everywhere you look, because the Google Maps API exemplifies ease of use and usefulness. And the Google Maps API documentation shows why it’s successful:

An API provides an interface for users, typically software developers, to pull what they need from your software and integrate it into their application.

So what does an API user want?

What do we always tell new (and old) technical writers? Know your users… and write with empathy for those users. Place yourself in the user’s shoes, and figure out what he or she needs to know to accomplish their task.

So let’s look at a typical API user. This person is a software developer, but perhaps does not think of herself as such. She is creating a software application, or maybe a web page or blog post, that requires what your product’s API can provide to do what she wants it do for her users. Maybe she needs streaming market data for her financial application, or perhaps she wants to offer a random shuffle of musical tracks from a popular music service on her website. The API you offer her is a means to an end, possibly critical to her work, but not of particular interest on its own. Our API user wants to make her code work with the API as quickly as possible so she can get on to solving other problems. The part of the code that interacts with your API is likely miniscule compared to the entire code base. Your mission as the API tech writer is to provide the documentation that lets her to do that.

Start with API design

Have you ever been asked to write documentation to solve a poor design? It’s soul-crushing. For API users, who do not have the tangibility of a typical onscreen product, poor design is even more harmful.

APIs must be designed in the same careful, thoughtful way that standard user interfaces should be created. Like technical writers who work with UI developers, to document APIs, you must involve yourself in the design process early on. With Agile methodology, that means getting participating in development sprints. Basic design principles like consistency are even more important for API users.

What does consistent design look like? Let’s focus on REST APIs, which are the most popular for mass-market use. REST (Representational State Transfer) refers to a set of API design principles that have proved surprisingly effective across a wide range of very different APIs.

In a typical REST API, a set of nouns (objects) interacts with a limited set of verbs (GET, PUT, POST, DELETE). The parameters for each of the nouns should follow similar patterns and conventions. The parameters should have data types that make sense and are consistent with each other. If a userID parameter is a string, while a customerID is a number, you are setting up the user for confusion. The actions of the verbs should be consistent for all objects.

Pearson offers a good tutorial on REST API design that can answer more of your initial questions.

The user’s first experience with your API

If you are a new user with a complex new product, what is the first thing you like to do? Successfully use it. As developer documentation expert Tom Johnson has pointed out to me, the user should be able to score a quick success with a rapid progression to “Hello World” when using an API. Searchify, for example, facilitates the use of their product with this simple “Hello, World” tutorial, and then progresses to more complex tutorials.

Note the careful construction of the steps, and how the user is told upfront about all the requirements to complete the tutorial. The tutorial allows the user a choice of programming languages.

After you complete the first simple tutorial, you can follow more tutorials that teach you the significant features of Searchify and how to use it in your application.

What tools and workflow to use to document your APIs?

At one time, technical writers typically used tools and workflows that were completely disconnected from the development of the code. Sometimes the documentation was deferred until after the product was completed.

With the advent of embedded online help, closer collaboration became necessary. With API documentation, you should avoid separation between code and documentation.

This does not mean everything has to be documented fully from the get-go. You can write the documentation necessary to create proper API reference documentation at the time of the code, for example, but defer writing tutorials until later. Not too much later, of course, as you want your first users to have access to this information.

Let’s look at some tools you can use.

General principles

As an API documentation writer, you need the help of your development team to write the documentation. Keeping all the work to yourself will ensure frustration and overwork. You will still have plenty of writing to do, but requiring that developers document as they code makes the process much simpler for you, and even helps the QA team.

This requirement that you involve developers in the creation of documentation means that you require a portable format that can be accessed with any text editor. You may have one developer who swears by emacs, another by vim, and another by SublimeText, and none of them will want to learn a new text editor. We all know how attached technical writers can get to their own tools, whether it be Microsoft Word or FrameMaker or MadCap Flare, and developers are the same. Fortunately, files created with different text editors are completely compatible, unlike with proprietary tools. API documentation can be composed as text files, and then processed with a static site generator to create attractive websites or PDFs. Here are a few text editors which I know to be popular among various developer factions:

Resist the temptation to limit yourself by giving only a few people access to a proprietary tool. Open-source tools are a popular choice for API documentation precisely because these docs require so much developer collaboration.

Markdown with a static site generator

Markdown is a popular and indeed ubiquitous document format nowadays. Markdown is a simple markup language that you can write in any text editor. Once you have the files created in Markdown, you then use a static site generator such as Jekyll, which is an application that transforms files created in Markdown nto HTML, PDF, or other formats. If your documentation in Markdown format is hosted on Github, your docs are automatically transformed into HTML with no effort on your part (although you may want to tweak the look).

You can be writing Markdown in minutes. It’s easy. The developers on your team know Markdown and love it. With the use of Markdown, you help erase barriers between the development team and the documentation team.

Markdown does have some limitations in terms of linking between different document sets, and many different versions of Markdown exist, because so many developers have added their favorite features to their own version of Markdown. However, Markdown is the preferred choice of many, as you can see by looking at various API documentation sets on Github.

reStructuredText markup with the Sphinx static site generator

reStructuredText is similar to Markdown, but provides more features, and is particularly suited to Python development. I appreciate the ease with which you can do file includes, create bibliographic entries, use LaTeX for mathematical equations, and connect between multiple documentation sets. Although reStructuredText is a bit more complex than Markdown, and the setup with the Sphinx static site generator can also be challenging, most users find it easy to use as well. Many users choose to implement the reStructuredText and Sphinx implementation provided by ReadTheDocs, as described here:

If your documentation needs more features than Sphinx provides, the Sphinx documentation describes how to extend its functionality by developing extensions, although this task requires developer-level skill.

Although Sphinx is most popular, other static site generators for restructuredText are also available, such as Nikolai.

RAML, Swagger, and API Blueprint

RAML, Swagger, and API Blueprint are all similar methodologies to describe REST APIs, and are used by developers to ensure their design is correct. However, the text files used by these applications to describe the API can then be used to present the API and its reference documentation. In this simple examTE) can act on each noun.

You can see more in-depth examples with the Watson APIs and their Swagger representations. Watson is the artificial intelligence engine that has beat human Jeopardy players, but it is used in a number of different contexts.

A Swagger implementation, and its equivalents, are not complete documentation. They represent the reference documentation in an attractive manner, but many developers like to have a plain text version available as well. Swagger also does not provide tutorials, lists of error messages, or the business context required for complete API documentation.

What documents and context to include?

Documentation should also include installation and configuration guides, if applicable, reference documentation including errors and exceptions, working and realistic code samples, and tutorials, as well as business-oriented documentation including blog posts and case studies.

Yogeshwar Srikrishnan, enterprise architect at Rackspace notes that “The most important piece of user experience for a developer who consumes an API is the developer documentation.” His article on REST API docs for Dzone details the most important aspects of developer documentation.
The need for good reference documentation is a given, so let’s start with setting the business context. It’s tempting to take what the marketing team offers and use that for business context. But that is unlikely to orient your user correctly. Give the user some ideas about how the API can be used. If case studies are available with reference customers, these can be useful to mention. Look at Twitter’s case studies for some great examples.

Spark the user’s creativity. With an Internet of Things (IoT) API, for example, some users think of ways to connect items that you would never guess could work together. Did you know that a Roomba has an API, and that you can use this API to turn a Roomba into a musical instrument?

Looking at other documentation sets will also give you an idea of what good API documentation should include. The PayPal API documentation site focuses on tasks you can do with the API, describes how to make your first REST call, provides references, gives you a dashboard for your apps, makes an online sandbox available to everyone, and so on.

Twitter API docs are also comprehensive and a good model to follow. Note that many third-party products interact with the Twitter API, so you also look at the documentation for those products for more ideas.

A new Twitter API user can start at the very beginning with a set of FAQs.

Installation and Configuration

If your API is not available publicly over the Web, then you will likely require that the user do some installation and configuration before using the API. This documentation can be a challenge to get correct, because so many of the small but crucial details change as your development team completes the API. Ideally, you should test your documentation with several different configurations to ensure your instructions are correct. If your user never gets the API installed, then she will not be able to use it. Accurate API installation and configuration documentation is critical.

Make API updates user-friendly

If you document APIs for which updates are frequently pushed to users, keeping up to date with documentation can be a challenge. But API updates can also be challenge for the user. Your product strategy is a company decision, but in general, preserving backward compatibility is highly preferred. If you must take away an older version of an API, give your users plenty of notice.

Agile methodology also provides good processes for ensuring up-to-date documentation. If a new feature is being developed, your process should prevent marking the feature complete until it has documentation. Ensure that general documentation has clear checkpoints for development and improvement.

Hosting your documentation online, or not

The advantages of putting documentation online where it can be easily searched are well-known. But it’s not always possible to put product documentation online. Your executive team may have legitimate reasons not to allow it. Decisions made by Netflix, and other companies limit the scope of their APIs to select users. But there’s little doubt that making your documentation publicly available increases the reach and usability of your API. A user can browse the documentation on her tablet while performing the listed steps, for example. Users can always ensure they have the latest documentation. Google indexes online documentation by default, thus greatly enhancing the search experience in a way that is harder to duplicate in a local environment.

Putting your documentation online at Github demonstrates that your company seeks connections with its developer users. You can get immediate feedback from developers about what is correct and useful, or not. For example, PayPal has made a great deal of content available at Github, including docs. And a quick look at the Github site for the SDK for PayPal for Android indicates the docs were updated seven days ago (as of this moment):

Test, test, test!

You do not need software development skills on on par with the senior developers on your team. However, you should know how to test the API to verify it works correctly as per your documentation. If you can create, or at least modify, sample code that uses the API, then you remove a significant hurdle for making code samples available to users.

Some typical tools for testing REST APIs include curl and Postman. You may need help from your development team to get these working for you, but your team is likely using these or similar tools already. With curl or Postman, you create the request that you want to test, and verify that the correct response comes back. A typical test would be to try different combinations of parameters, to ensure that they work correctly together.

For other APIs, determine the best approach for testing your documentation in consultation with your development team. Be clear that having accurate, working documentation is a high priority to you, and you want to ensure that what you write is correct. You cannot do serious documentation without checking your work.

In summary

If you want to document APIs, know that it requires the same careful attention to detail required by technical writing in general. You must provide both the high-level business context and small implementation details. You have to assert yourself as a member of the development team, and involve the entire team in the documentation effort.