Your team has built an excellent API, and now it’s time to demonstrate its power to the users.
A spreadsheet listing all the functions won’t cut it. Instead, you have to guide your readers through the API and show them how to use it—all that while balancing the right amount of information.
Don’t worry, writing great API documentation doesn’t have to be too complicated.
We’ve selected six API writing tips to help you provide your readers with an exceptional user experience and streamline your document creation process. Let’s see what these are.
Tell Users Where to Start
Between code examples, edge cases, FAQs, and more, API documents contain a lot of information that can overwhelm the users.
To help your clients start using the API quickly, you should provide them with a clear starting point. That way, you’ll turn your API docs into a valuable, actionable resource.
Let’s see an example of API documentation which does exactly that with a “Start here” section.
The image above shows the API introductory section of Twilio, a customer engagement platform.
Besides describing the core concepts of the solution, the authors have also acknowledged the devs who just want to dive into the API.
That’s why there are clickable links that show you how to get started with different SDKs.
Selecting an SDK then guides you to specific steps you have to follow to incorporate Twilio into your apps.
Twilio maintains the same content structure throughout the entire API documentation.
Let’s say you’re looking to add videos to your app.
While Twilio provides an overview of the video feature and additional materials, you don’t have to read through all that to get to your solution.
Instead, you can use the table of contents and see the instructions directly laid out.
Because of that, you’ll know you first have to create an Access Token server, and the documents will show you exactly how to do that.
Writing your API documents as straightforwardly as those at Twilio will ensure that your users always know how to get things done.
Read recommendation: How to Write Technical Documentation: Step-By-Step Process
In an ideal world, everyone would read the docs cover to proverbial cover.
Still, developers rarely have that amount of time, which is why they only scan the documents for relevant information.
So, if you want to help new users implement your solution efficiently, make sure your API documents contain precise instructions on where to start.
Follow the Naming Conventions Consistently
Great API documentation is easily understood. One of the best ways you can increase the comprehension of your API documents is by consistently following the naming conventions.
There’s a good reason why many technical writing style guides prioritize consistency in writing.
Consistent naming helps your readers follow the content more easily and also improves the searchability of your API documentation.
Ensuring the internal consistency of your writing is a good starting point.
However, developers don’t like surprises when they work, so it’s also vital to follow the established naming conventions whenever you can.
RapidAPI, the world’s largest API hub, has a helpful guide for naming API endpoints.
The company also lists conventions for naming uniform resource identifiers (URIs) and other parts of the API.
Some of the commonly cited naming conventions include favoring nouns over verbs, as well as hyphens over underscores, and using lowercase letters.
Here’s what the conventions we’ve just listed could look like in practice.
In addition to sticking to the industry-standard naming dos and don’ts, you should also consider abbreviations when writing API documentation.
While abbreviations make function names more compact, they obstruct readability, and you want your API documentation to be clear.
That’s why most developers speak out against abbreviations in code.
Of course, that doesn’t mean that you should turn each HTTP into hypertext transfer protocol, but you should definitely pay attention to how you use acronyms and other types of abridging.
All in all, since the goal of API documentation is to present the users with accessible information, you should keep your writing clear and concise.
Following the standard naming conventions will help you make the API and its elements meaningful and informative, providing your users with a great developer experience.
Call Out the Common Use Cases
If you want to take your API documentation to the next level, you should list real-life use cases for it.
That way, you’ll transform your API from abstract lines of code into a tool that brings users tangible, measurable value.
There are two main types of API documentation consumers: developers and non-technical stakeholders.
Developers usually turn to API documentation when they want to accomplish a particular task with the API or when they encounter a problem while using it.
Either way, they’re rarely interested in browsing general information about APIs.
Calling out common use cases for your API will help the devs get to the specific information quickly. Slack’s API documentation is an excellent example here.
The image above shows Slack’s messaging API. It’s neatly divided into message retrieving, sending, modifying, and other related actions.
So, if a dev had a problem with scheduling an automatic message announcing the weekly meeting, they’d immediately know where to look for a solution.
Similarly, Slack assigns descriptive names to actions to help users navigate the API documents.
Actions such as “send information into a Google Sheet” or “add new deals to CRM” make it easier to find the relevant instructions when you need them.
To write great API documentation, you should consider what your users are trying to build and list the use cases accordingly.
However, you shouldn’t forget about non-technical stakeholders, either.
API documents also play a role in marketing, meaning that elegant documentation can get you more sales.
Calling out the use cases of your API in plain language can help you attract project managers looking for new tools for their team.
Quick read recommendation about tools: Top Tools for Documenting Your APIs.
For instance, this part of Slack’s API website presents how the solution helps reduce repetitive tasks.
As you can see, the functions are described without jargon, making the content more approachable and attractive to non-technical stakeholders.
To sum up, API use cases are in the gray area between developer documentation and marketing materials. Fortunately, you can use the duality to your advantage.
By stating the uses for your API, you allow developers to navigate the API more easily and attract potential customers.
Therefore, if you’re looking for an effective way to round off your API documentation, don’t forget to write about the common use cases.
Use Examples in Your API Documentation
There’s no better way to increase the usability of your API documentation than by listing examples of calls, errors, and other operations.
These examples allow a hands-on approach to the API and reduce the time it takes users to get familiar with it.
Providing a high-level overview of your API is a great way to show the readers the full picture of what they get when they use your software.
Still, while such content can be beneficial, you have to keep in mind that it will likely get ignored.
That’s right, a study on improving API documentation has found that almost half of the developers skip the conceptual elements of the docs.
Instead, they dive straight into examples. Such a bottom-up approach lets them learn about the API in a direct manner.
So, what kinds of examples do you need in your API docs?
Again, it’s best to think of the common use cases and list the elements the user needs to implement the solution.
You should, therefore, describe calls, responses, and errors for each action.
Here’s how Stripe API documents list examples.
The screenshot above shows the routes developers can take with disputes, such as retrieving, updating, and closing them.
Each route comes with a concise description, parameters, and sample responses.
These specific examples let the developers see what they can accomplish with the API and even copy parts of code to test the solution immediately.
Seeing that examples have been voted the most important element of API documentation year after year, you should ensure yours are always polished and illustrative of your API as a whole.
Offer Additional Content
As we’ve seen so far, each API document needs strong foundations. But if you want to go the extra mile with your API, you should produce extra content, such as tutorials or case studies.
The Parson AG study we’ve referenced earlier has shown that 45% of developers focus only on the essentials of the API.
That finding, however, tells us that the other half of developers are interested in additional materials API documents offer.
So, to cater to all your audiences, you could consider creating bonus content that explains the bases of your API or sheds light on its intricacies.
For instance, the CLI tool Datree provides users with video tutorials for setup.
This type of content is intended for entry-level users who haven’t yet used the software.
The video tutorial is followed by helpful screenshots and further instructions, so that absolutely everyone can benefit from the content, regardless of the preferred medium.
On the other hand, you could also create content for more knowledgeable users, or those interested in more details.
For instance, you could write case studies to demonstrate how your API benefits those who use it. Here are some examples of case studies about the different uses of Slack’s API.
These articles, hosted on Medium, are fairly casual in form.
They describe how other companies and individuals use the Slack API, what benefits they get, and what their plans for the future are.
Slack also hosts additional tutorials on GitHub, keeping the official API documentation neat and uncluttered.
It’s worth noting that additional materials are a bonus supplementing your main docs—you shouldn’t place essential information in the extra articles that most of your users may not read.
Still, additional content can help you highlight some of the less obvious uses for your API, emphasizing its potential.
Encourage Users to Provide Feedback
Although you’ve reviewed the documents before publishing and asked your team to do the same, you’ll be able to determine the success of the docs only after you get the feedback from your actual users.
So, don’t hesitate to ask for it!
User feedback is a valuable resource for establishing the further course of your technical documents.
In addition to pointing out the broken links or code errors, comments from your users can also tell you whether your documents are informative enough.
However, it’s unlikely that users will take the time to email you their opinions.
That’s why you’ll stand a better chance of receiving feedback if you embed the request directly into your documents.
The image above shows how we collect feedback on the docs for Archbee, our product and API documentation tool.
Here at Archbee, we place feedback forms, like the one from the screenshot, at the bottom of each of our documents.
According to Tom Johnson of I’d Rather Be Writing, placing the forms at the bottom of the document is the best way to collect feedback.
Johnson also advises companies to keep the procedure of leaving feedback short and simple.
“If your feedback form requires developers to log in, or to proceed through a series of authentication screens, or do anything else requiring more than 5-10 seconds of their time, your engagement rate will go down.”
So, you shouldn’t be afraid of asking for feedback—just make sure that it’s easy for the users to tell you their thoughts.
And once you receive feedback, it’s essential to act on it.
Establishing a document maintenance plan will help you review the comments you receive in a timely manner and update your documents to serve the users better. Here's a blog post about it: Benefits Of Using a Documentation Platform for Maintaining Your Software Documentation.
Conclusion
An API is only as good as its documentation. And to make your docs shine, you need to approach writing API documentation with care.
We believe that these six tips for writing great API documentation will help you write informative and compelling documents.
With great documentation, more people will start using your technology and ultimately become loyal customers.
So, after you’ve spent so much time developing an excellent API, it’s only fair to supplement it with equally helpful documents.
