Write the Docs: Lois Patterson – What Makes Good API Documentation: An Example-Based Approach

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Lois got interested in this subject through working on an API product she had to document. The company she works for has a very complex project that they were building an API for. They saw the API as a means for letting developers to narrow the scope of functionality available to certain user bases.

To start on this project Lois researched other good API doc sets on the web. What she found was that if you have a good API the docs are quite likely to be good as well. Twitter, Github, Facebook, and Flickr were cited as examples here. Why are these good APIs? First, they segment documentation in to buckets. Twitter has API documentation broken in to tweet, user, and other specific aspects. Similarly Flickr’s API Garden gives you concrete examples of how other developers have used the API.

While there aren’t inherent API standards those APIs which become extremely popular become de facto standards. The ProgrammableWeb service is a good resource for searching through various public web APIs.

Swagger and Atlassian’s REST browser are handy tools for exploring and testing the content within an API.

Lois argued that any good API documentation should have good descriptions, tutorials, code examples (both snippets and working apps), a sandbox test environment, as well as FAQs. At Lois’ company someone tried to argue that code examples weren’t needed because, “any good developer can figure out how to make a working application.” While they may be technically able to figure it out the job of your API docs is to make that process easier. Clear versioning for the API as well as suggestions on using the API are also helpful.

A first pass on API docs can be as simple as taking the spec and turning it in to a user-facing doc. Taking that to the developers then gives you feedback to go from and get a set of points to clarify.