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?
Before diving into API documentation, let me briefly explain what an API is and its basic functions.
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?
APIs are built by software developers. Since software developers are directly involved in building and using APIs, it is easier for them to create the 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
When writing API documentation, start by creating several outlines. This will give you an overview of what you intend to write.
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
This is similar to the abstract page of a project report.
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.
This is the primary part of the documentation.
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.
Once you’ve explained how the API works and/or provided itemized steps, it’s a good idea to show examples of calls, responses, error handling, and other operations that have to do with how the developer interacts with the API.
Though this is optional, I recommend adding a glossary page for your API documentation.
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
As we just discussed, you should have first-hand knowledge of the API you are documenting. Remember, your goal is to guide potential users who might not have any knowledge about the API. You wouldn’t want to confuse them, right?
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
API documentation is not restricted to written guides alone. You can use short videos or PowerPoint slides to illustrate the integration of the API.
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
APIs are guides for software or hardware, so you’ll need to use some technical terms when writing the documentation. If you’re trying to be a technical writer, resist the temptation to be ambiguous.
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
Documentation is easier to understand if the content is itemized. This is a major reason to write concisely.
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
As many times as you read a document, there’ll always be something to change, update, or even delete. This is a typical experience with writers, and it shouldn’t make you upset.
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
Writing API documentation can be quite time-consuming and difficult to maintain. But a good documentation tool can alleviate most, if not all of these issues.
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 is a platform for building and maintaining APIs with features for creating API documentation.
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 is an open source API Documentation tool that offers various themes for creating your document. This tool combines diagrams, specifications, and other content types to give you better documentation.
It has the advantage of allowing authors to write in GitHub flavored markdown, but updates for this tool are irregular.
SwaggerHub is a popular API documentation tool for many technical writers because it’s interactive and easy to use.
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
Below are some APIs documents that will inspire you to start writing great API docs. Each of these documents details the usage of the product API to developers in easy steps and understandable terms.
GitHub API Docs
GitHub offers really helpful documentation — which is no surprise. Check out their API docs here:
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
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
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.
Documentation lays out how a tool works so others can use it properly. API docs aren’t always easy to create, but it’s not as difficult to create helpful documentation as you might think.
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.