Why You Should Let Robots Help You Write Your API Documentation

ReadMe -

Creating clear, beautiful documentation is one of the biggest pains of being a developer. That's why autodoc tools like Rdoc are so appealing. Type a line in your terminal, and like magic, you get an HTML file filled with your API specs.

The problem is that the results end up looking like this:

# Generic Namespace exception class
class Namespace Error < Standard Error
end

# Raised when...
class SpecificError < NamespaceError
end

In 2009, Django founder Jacob Kaplan-Moss pointed out that "most of the time it's easier just to read the source than to navigate the bullshit that these autodoc tools produce."

He has a point. Taking a computer-generated doc and sticking it on your developer site is like handing someone a dictionary and asking them to learn English. They're great when someone's stuck or needs to look something up, but with only a dictionary, nobody can properly learn.

Computer-generated tools are now sophisticated enough to do a lot of the heavy lifting—but they won't show people how to actually use your API.

It's up to you to take care of the last mile, and provide people with enough context to get started with your API. By using a mix of auto-generated tools and a human touch, you can get more people up and running with your API and straight into your app.

Where Autodoc Tools Come into Play

Once upon a time, if you wanted to include code snippets for how to use your API in a different language, or a reference library for each GET and POST call, you had to mark them up by hand. This meant that documentation took forever to produce, was often filled with errors, and had to be updated every time the source code changed.

Tools like Swagger and API Blueprint make this a thing of the past. Autodoc tools now take care of a lot of the headaches around producing great documentation.

Clearbit's documentation does this beautifully. You can use Clearbit's API to find out everything you need to know about a lead, from their company to their email address. Clearbit automatically generates code snippets Ruby, Node, Python, as well as a Unix shell—making it easy for users to get start prospect right off the bat.

Autodoc tools are great for producing:

  • The skeleton of your docs. Good APIs speak in a common language that everyone can understand, which is one of the reasons why we love Swagger. Swagger provides the blueprint for your API documentation. It takes in your JSON or YAML file, and spits out an interactive doc and a roadmap for building out your API even further.
  • Reference libraries. An API's reference library gives an overview of all the different REST calls possible with the API. Swagger, RAML, and API Blueprint all help you parse your app's code and turn it into a library. Having a reference library is important for seasoned developers who already know how to use an API, but it won't be enough for everyone else.
  • Code snippets. If you include the code snippets for 6 popular languages on your documentation site, with 15 API endpoints, this means 90 code snippets to keep up to date. Autodoc tools like Swagger and API Blueprint take care of this for you, and automatically update when you change the source code.

As you improve your product, your API will be able to do more things—but it will also grow more complex. Autodoc tools allow you to scale your documentation with what you're building.

You Need a Human Touch....For Now

While computer-generated tools can produce resources, they're not great at actually welcoming people into your API. They don't know what parts of your API are more important and should be emphasized, nor do they provide examples of how to actually plug your API into someone's app.

That's up to you. Humans understand other humans. They can describe how the API works in plain English, provide concrete use-cases and examples, and help someone without much coding experience to get off the ground making calls. That's why it's so important to get a human touch in your API documentation.

Mailgun, for example, uses autodoc tools to generate your standard API reference library and code snippets. But its documentation is clearly written by a person, to a person. In a handy quick-start guide for new users, Mailgun's documentation strikes a conversational tone—“It's up to you, whatever you find is easier is fine with us.”

Let computers do the heavy lifting, and let the humans reorganize that information in a way that will make sense to other humans.

Getting real people to help craft your documentation allows you to:

  • Explain the edge-cases: Your API will always have specific edge-cases and utilities that aren't covered by tools like Swagger. Maybe, like Twilio, your app allows calls to your API to trigger text messages or phone calls. An autodoc tool won't be able to understand that, let alone explain it.
  • Humanize documentation: Autodoc tools tend to spit out lines in documentation like “POST /user/new” Your documentation becomes much friendlier when you replace that with a title like “Create New User.”
  • Handle errors and common mistakes: Robots assume that everyone who uses your API is also a robot. In reality, many of the people who take your API for a test-drive won't be perfect coders. Provide them with a common mistakes section in your documentation.

There's no AI super-power (yet) that will magically cook up your documentation. If you rely 100% on autodoc tools, you end up with a bunch of static HTML files. The results are only legible if there's a human on the other end to put together the pieces of the puzzle.

Robots + Humans

Some of the people who use your API will be seasoned developers who only need a reference manual to get off the ground. Others will be novices who are interested in both.

The best API documentation leverages both tools and human resources to create a tailored experience for every type of customer.

Create documentation that's as clear for a developer at Facebook, as it is for the kid in Korea who's building the next Facebook. That's what will get your API actually used by the bigger software ecosystem.