A Guide to Writing API Documentation

Sharing innovative code has benefited software development since its inception. However, developers often overlook the documentation that accompanies code.

The role of documentation is hardly trivial. Documentation engages the community and piques its curiosity with a product that would otherwise look like endless lines of incomprehensible code. The documentation then decodes the code, so to speak, and reveals the meaning and structure that the developer invested into it. Finally, documentation teaches developers, letting them learn in a short time something that was built through blood, tears, and hundreds or thousands of hours of thought and effort.

Read Sendbird’s documentation for its real-time chat and messaging API

This is a brief guide to writing effective API documentation. But I hope this long introduction conveys to you the gravity of software documentation. It’s like a black hole. It might feel as if it were tearing you apart into oblivion. But who knows what discoveries lie on the other side?

The rest of this guide will succinctly outline key issues to consider when designing your own documentation. Whether you are SaaS or an individual developer launching your own library, this guide will hopefully help you provide an enjoyable learning experience for your readers.

Structure

The overarching structure of documentation might be the most difficult part to get right. Aim for a clear and intuitive structure. It will provide great relief not only to fledgling developers but also to internal contributors hoping to maintain consistency as they add new information to the documentation. Some tips and examples will be provided below.

1. Invest in a solid introduction.

You probably spent hundreds, if not thousands, of hours developing your product and its the platforms. But remember that your users have not. Even things that seem basic to you might not be intuitive to a fresh pair of eyes. So use the introduction to acquaint a new user to the basic concepts of your service and its underlying platform, whether it be an OS like Android, or a language such as Java or Swift.

The Sendbird documentation provides an example. The Platform API provides a section on URL encoding and multipart requests–concepts ubiquitous to HTTP–and a section on the basic setup steps for Sendbird itself. This may appear to be overkill. “Who doesn’t know,” you might ask, “about URL safety?” But you would be surprised how many bug reports could be nipped in the bud with such simple additions.

Of course, there is always a danger of explaining things that do not really need explanation. Is it better to be safe than sorry? Not always. Aim for instruction rather than redundancy. Needless explanation should be avoided just as much as excluding basic concepts. That said, experts often underestimate the needs of the novice. If it helps, imagine you are an instructor in a classroom teaching students in their second or third year of study. What would aid

the average student?

2. Let your reader try the core feature as soon as possible

APIs, libraries, and SDKs often provide one core feature. Sendbird provides messaging integration. Firebase Database offers a real-time database. Stripe enables developers to receive online payments easily. Although these services provide other features, they tend to have one goal: implement the core functionality. You don’t want users to learn about sending encrypted files before they learn about setting up the API. Give them a starting point so that they can attempt the advanced features on their own.

Stripe provides a brilliant example. Go to their docs page: https://stripe.com/docs. You will immediately see an interactive “Try now” section that lets you try out the payment API in a couple of minutes. The documentation ignores the details about configuring the API with credit cards, users, charges, and subscriptions. This allows a developer to try out a working implementation.

3. Avoid excessive nesting

It might be tempting to subcategorize everything into logical groups. Avoid excessive nesting.

Here’s an example:

1. Messages
    1.1 Sending messages
        a. Sending text messages
        b. Sending file messages
            i. Sending binary files
                * Multipart requests
                * Using multipart requests to send binary files

First, it makes sections difficult to locate. A side navigation menu would not be able to display sections nested deeper than 2 levels. In fact, it might be ideal to extend only a single level. The second problem relates to good design. How would you distinguish all the headers–h1 to h6–so that users could intuitively know exactly where they are in the documentation?

One solution would be this:

1. Messages
    1.1 Sending text messages
    1.2 Sending file messages
        a. Sending binary files
          (+ explain multipart requests with a plain untitled paragraph)

By flattening out the structure of your document, you are striking a balance between categorization and findability. It would make logical sense to group “sending text messages” and “sending file messages.” But simplicity is invaluable for a developer looking to find a solution to a problem in the shortest amount of time.

Formatting

Modern developer documentation places great importance on design and formatting. Take as an example the Gmail API docs. Colored boxes enclose important notes. The documentation highlights key paths in endpoints. Tables present information in a concise and readable way. Stripe’s API reference is beautifully designed. Its two-column layout maximizes real-estate on the screen.

When planning your own documents, envision how things should be displayed. Remember that designed elements must be reusable and consistent in diverse contexts.

1. A lightweight markup language is a proven option

Since documentation is typically rendered on a website, it is based on HTML. However, using raw HTML to write documentation is bound to be time-consuming and also mistake-prone. An LML such as Markdown makes writing for the web fast and efficient.

Let’s say you have a header, a paragraph, and a link within the paragraph. HTML would require something like this:

<h1>Header here</h1>

<p>Reference this <a href=”https://www.example.com/”>link</a> for a more detailed description.</p>

Compare this with the same content written in Markdown:

#Header here

Reference this [link](https://www.example.com/) for a more detailed description.

2. Make it one page–unless you have a very good reason

No one wants to click through three nested links to find the answer to a simple question. One-page docs provide unmatchable searchability. Let’s face it, you can’t beat ctrl-F. Provided you have a sidebar listing all the sections, a single page of documentation allows the get a bird’s eye view. See for example the Parse Android docs. You can see that Parse contains components such as Users, Objects, and Sessions without consulting a separate “table of contents.”

But let’s say you have an extensive API. Squeezing all that information into a single page would be inconvenient and lead to slow page loads. Try to avoid this too. One great example to follow is GitHub’s API docs. They keep a persistent sidebar but load each document in a single page.

3. Use tables

Code documentation inherently contains a lot of information. Using tables conveys information succinctly, especially for code parameters and variables.

This article by Peter Gruenbaum recommends a 4-column structure to document example requests and responses.

Sendbird follows a similar structure but uses 3 columns, opting to merge “description” and “remarks.” Tables with too many columns don’t often display well on websites. You should therefore strike a balance between adding additional columns and writing things out in a general “description” column. Should you have a “required parameter” column? A “default value” column? Or should you just add that to “descriptions”? The answers to these questions will depend on the design of your API.

Writing and grammar

You may find the grammar involved in technical writing to be a bit tedious and, well, overly technical. It doesn’t leave much room for exquisitely baroque metaphors or sentences that wind gently across the screen only to tickle you at their conclusion. Ahem. That aside, we outline some general rules below.

1. Address the reader using “you” and use active voice

It’s now conventional to address the reader with “you.” Look to the local internet behemoth, Google. “You” abounds in its documentation. It also encourages you to write in the active voice. Since your documentation is an instruction manual for an individual developer to do something, your writing should emphasize the agent and their action. Not: “Code is written by a developer.” Rather: “A developer writes code.”

2. Use the pronoun, “they,” to be the most inclusive

It is cumbersome to always write “he or she.” Yet, it is important to include both men, women, and other genders among your readers. Although it is technically incorrect to use the plural pronoun to refer to a singular noun, it serves our mission well. Therefore. “They” rather than “he or she.” “Him and her” ought to be “them.” How’s that for chiasmus! Let’s use an example. Many API documents talk about “users.”

Do NOT do the following:

“A user might encounter X. In that case, you could provide him with feature Y.”

Just use “they.” The following isn’t so bad, right?

“ A user might encounter X. In that case, you could provide them with feature Y.”

Or use plural throughout!

“Users might encounter X. In that case, you could provide them with feature Y.”

3. Keep the title capitalization consistent.

There are two main types of capitalization used in titles: “Cooking a Great Apple Pie” and “Cooking a great apple pie.” The first capitalizes major words according to a standard like AP or Chicago. We call the second example sentence case. For long titles, sentence case tends to be more readable, but it’s ultimately up to you. Just be sure that you and future contributors are consistent.

Conclusion

The API may be the interface between an application and backend code, but the documentation connects you and your users. Writing great documentation is no trivial task, and will likely be an iterative process of feedback and revision. Hopefully, this guide is a useful starting point. And like our documents, it is open to feedback and improvement. Your thoughts are always appreciated.

Happy writing!

Links

The greatest references for writing documentation are actual docs pages. Twilio and Stripe are frequently cited as examples of great design and writing. Google and Facebook are also key examples to consult. And our own documentation isn’t too shabby: https://docs.sendbird.com.

Articles and style guides are also very helpful. Writing the docs provides a detailed guide for developers writing documentation. Google’s documentation style guide is concise and provides best practices. Parse’s article on designing API documentation is also an informative read.