Good API documentation Guide

Imagine that you just bought a new home theater system and you go to set it up. What do you do first?

Thank goodness you have a handy device manual to help you out. You just need to follow the steps detailed in the manual, and voilà! Your home theater system is ready to blast your favorite songs.

Just like how a device manual guides you through setup and installation, API documentation can help guide you through configuring an API.

What is API Documentation?

API is an acronym for Application Programming Interface.

Whether you’re a beginner coder or an advanced developer, you’ll come across this term often in your software development journey. It is the bridge between your computer, mobile phone, or application and external resources.

In other words, APIs give your software the ability to interact with other software programs, databases, or resources. Instead of writing the program for a particular feature of your application, you can consume a readily available API of a similar feature.

Many APIs are public (free) while others are private and require payment for a private key that lets you access the API. There are different types of APIs like REST (Representational State Transfer), SOAP (Simple Object Access Protocol), and others.

Moving on — so what is API documentation? Well, it’s a written guide stating the functions of the API, how to integrate it into your program, and use cases for the API, along with examples.

Keep in mind that API documentation is technical content. This means it will contain some technical terms, but should still be readable and easy to understand.

Who Should Write API Documentation?

The downside of software developers writing API documentation is that they write from a very technical angle, which can make the document quite difficult to comprehend. Another issue is that it will take more time for the API developer to create the document while also developing the API.

So a good alternative is to assign the task of API documentation to a technical writer. A technical writer is someone who combines the expertise of content writing and technical knowledge to produce documentation that’s not only technical, but also informative and understandable.

The technical writer learns about the API from the API developers, then creates tutorials, examples, and other content for documentation purposes.

Meanwhile, the API developers oversee the technical writer to ensure that the written documentation is accurate, and they can provide more information to the writer when necessary.

The goal is for everyone to work together to produce documentation that fully explains the API and guides users without confusion.

If you’re interested in writing documentation for an API, but don’t know where or how to begin, this article will help you get started.

I can feel your excitement from here, so let’s dive in!

How to Start Writing API Documentation

The next thing is to gather information for each of the outlines you created. This can be achieved by getting the API description, the language used, other references, and sample cases from the API developers. You can also view a live demo of the API so you have first-hand experience of how it works.

Lastly, combine the details you gathered and arrange them in a logical sequence.

Remember to proofread your document and share it with the API developers for any corrections or additions before going public.

Now that you know where to start, how can you put the bits together so that they become a meaningful whole?

What to Include in API Documentation

1. An Overview

The overview should contain a summary of the API and the problem it is solving. It could also include the benefits of using this particular API over other similar APIs.

2. Tutorials

It should include the different content formats you are using to explain the concept of the API to the user. It can also include links for reference and a step-by-step guide for integrating the API and consuming it so it functions properly.

3. Examples

4. Glossary

To avoid boring the user with long text blocks, explanations of various terms, schemas, images, and so on that you use throughout documentation can all be pushed to the glossary. Then you can reference these things in the documentation, and link to the glossary.

How to Write Useful API Documentation

Know the API

If you have a solid understanding of the product’s architecture, functionality, and other vital information, you’ll be able to write the product description part of the API effectively without doing any guesswork.

If you are not well informed or fully convinced about the API you’re writing about, take some time to do your research and gather as much information as you can. Use the API yourself so you gain important insight into how it works.

Use Relatable Content

State different use cases while writing the documentation. This will help readers recognize which one is similar to theirs, or find one they can relate with easily.

Also, include some code snippets where and when you think they’re necessary. This will make it possible for readers to follow along as they go through the documentation. Just like the popular saying goes, “Tell me and I’ll forget. Teach me and I’ll remember. Involve me and I’ll learn.”

Be Clear, Even If You Need to Be Technical

A good document isn’t one with complex grammatical constructions, but rather, one that is relatable, straightforward, and clear. It can only be relatable when it is written in simple and understandable language.

Your API documentation should be in the simplest form possible, yet it shouldn’t leave out any important details. Also, make sure you explain acronyms and tech terms the first time you use them, or put them in a glossary toward the end of the documentation.

Itemize the Guide

Numbering or itemizing the guide in steps helps the user figure out what to do at every point in time. It’s similar to reading the alphabet from A to Z.

With clear steps, users can easily go back if they run into an error.

Check For Errors

Gold passes through several fiery furnaces before it becomes refined. Let’s just say your documentation should go through a similar process (not a fiery furnace though) so it comes out as a well-prepared document.

A thorough review process can help you minimize any errors and produce clear documentation.

The Best Tools for API Documentation

There are numerous tools out there to make your journey of API documentation easier. The benefit of using tools is the collaborative features and standard templates these tools provide, rather than starting from scratch.

Below is a list of some popular tools and their advantages.

Postman

Postman uses its machine-readable documentation tool to make the API documentation process easier and faster. You can sign up to Postman for free and install it on your PC.

Although Postman provides updates to all API documentation it produces automatically, its UI may be difficult to understand at first.

DapperDox

It has the advantage of allowing authors to write in GitHub flavored markdown, but updates for this tool are irregular.

SwaggerHub

Though it’s beginner friendly, it requires payment for anything other than personal use. So if you’re part of an organization and want to use SwaggerHub, your organization will have to pay for it.

Whether you’re selecting the tools listed here or an alternative, you should consider the following:

  • What setting will you use the tool in? Is it for personal use or as part of an organization?
  • How technical are you? Are you a beginner or expert?
  • How is the user interface and user experience?

Some awesome examples of API Docs

GitHub API Docs

Getting started with the REST API — GitHub Docs

Learn the foundations for using the REST API, starting with authentication and some endpoint examples.

REST API is a popular API used by Developers to access data from the web or a database. This documentation by Github includes an overview, guides, and even code on how to use REST API in your program.

The interesting part of these documents is that you can easily understand it irrespective of your skill level.

Paystack API Docs

Build amazing payment experiences with the Paystack API

docs

Are you building an application that requires payment? Paystack is a fintech solution for payments. Their team provides detailed information for developers on how to use the Paystack API in your programs. It is more like providing a handbook on using the API to avoid confusion when consuming the API into your program.

Twitter API Docs

Programmatically analyze, learn from, and engage with the conversation on Twitter. Explore Twitter API documentation now.

The Twitter API documentation explains how developers can interact with the App. The documents clearly detail different sections (user, tweets, direct messages and so on) and their operations.

Although permission access is required for more information, you can access the basic ones with just a click on the link.

Conclusion

Just remember: start by writing your first draft, improve it daily, and seek help from mentors or senior colleagues when you are stuck.

Now go on and write that API documentation that will ship with the next world-class product.

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store