Creating and maintaining high-quality API documentation is immensely challenging.
Such documentation is a source of information about your APIs that should be reliable, useful, comprehensive, and easy to read.
With that kind of responsibility at hand, mistakes can happen to any writer.
Luckily, if you’re reading this, there’s a good chance that you’ll learn to avoid them.
In this article, we’ll warn you about the most frequent mistakes you can make with API documentation and how to make sure you don’t make them.
Let’s start!
Relying on Documentation Generated From Code
Creating API documentation is a challenging task that requires a lot of planning, hours of focused work, attention to detail, testing, etc.
In short, it is a big commitment, so wanting to save some time and resources that would normally go into it is an understandable impulse.
That’s why more and more companies use a shortcut and rely on API documentation generators that produce documentation from code.
It’s much faster than manually writing documentation and doesn’t require as much effort and skill.
However, relying only on code-generated documentation is a mistake. Peter Hilton, a product manager and author, explains why:
In other words, documentation generated from code can’t provide users with all the necessary information that the documentation written by a developer or a technical writer can.
It can’t explain what a user can achieve with an API, its benefits, or how it works, nor can it provide the best practices and tips for using the API to its full potential.
Because we mentioned about best practices and tips for using the API to its full potential, we can suggest you two very good article:
For example, below, you can see an example of documentation generated by Swagger, one of the best-known tools for that purpose.
Documentation like that can undoubtedly be useful for developers. It has code examples and a list of operations for APIs.
On the other hand, what it can’t generate from code is something like this part of the Instagram Graph API documentation:
As you can see, it’s a bulleted list of common uses for the Instagram Graph API.
In addition to that, their documentation also describes what it is used for, who its intended users are, and the API’s limitations.
There are other helpful sections in the documentation, for instance, a Getting started guide with the instructions complemented by visuals.
Users want information like that in their API documentation because they turn to it for different needs, from tutorials to use cases.
Providing them only with the documentation generated from the code would result in an incomplete resource.
So, if you use a tool for API documentation, you should use one like Archbee.
It allows you to combine the best of both worlds—automatically generate API references and expand upon them with custom blocks where you can explain what the API does.
That will allow you to provide your users with comprehensive API documentation that contains everything they need.
Neglecting to Add Important Sections
As we’ve mentioned earlier, your API users are approaching API documentation with the expectation that they’ll find all the information they need to work with those interfaces successfully.
To meet their expectations, you should avoid making the crucial mistake of failing to include important sections in your documentation.
Otherwise, all you can offer your users is an inadequate resource, which can cause frustration and dissatisfaction.
One of the must-have sections in your API documentation is certainly a list of status codes and error messages.
Sooner or later, developers will face an issue using your APIs. When that happens, it’s vital that they know how to proceed.
A section with possible errors and explanations, like the one from Twitter below, is precious in those situations.
It should contain a code, a text that appears with it, and a description of what the error means and what caused it.
If users don’t have that information, they’ll be stuck with an error and inkling of what it means, why it happened, or what they can do to fix it.
Another section that would be a significant oversight not to add is one about authentication.
Your documentation should provide clear information about authentication since it’s one of the first things they need to do to start working with your API.
For example, if your users need access tokens, the authentication section should provide all the information about obtaining them, as the Slack documentation does.
They list three steps that lead to gaining an access token and elaborate on each.
Neglecting to do so would put users in an unfavorable position of figuring out authentication and authorization on their own or spending time on the back-and-forth with your customer support team.
Next, a section about HTTP requests should find its place in your API documentation.
The HTTP protocol for requests identifies what actions users can take through your APIs, so that information is undoubtedly important.
For example, Mozilla, in its API documentation, lists HTTP methods and explains what each one does. Below, you can see some of them:
They also provide a list of specifications, and readers can click on each one to learn more about the specific method, when to use it, and other valuable information.
The sections about error codes, authentication, and HTTP requests are among the most important ones for your users.
Not including them in your API documentation would be an omission that might cause your users to abandon your API and look for other solutions.
Not Providing Examples
Describing your APIs and all of their elements in detail is crucial if you aspire to create high-quality API documentation.
However, you can go further than just describing and writing about your APIs.
Most developers want to read clear and well-written documentation, but what they want even more is to see what APIs are capable of as soon as possible.
One of the most efficient ways to show them that is to provide code examples in your documentation.
As Tom Johnson, a technical writing expert, sums it up, it’s all about code.
And he’s far from being the only one who regards code examples in the documentation as vital.
According to a survey by SmartBear, developers consider examples the number one feature they look for in API documentation.
The data above shows that 70% of developers considered examples the most important API documentation feature in 2019.
Although the percentage lowered slightly in the next two years, examples are still at the top of the developers’ lists when it comes to documentation content.
That clearly indicates that neglecting to provide them would be a big mistake.
It’s not surprising that examples are held in such high regard.
They make the implementation of APIs easier by showing developers how they work before they even need to figure that out themselves.
For example, Mailchimp provides code examples for numerous features of their APIs.
The example above is for listing automated emails.
On the right-hand side, you can see a code example in Node.js. Mailchimp also provides examples in Bash, PHP, Python, and Ruby.
That way, they provide many examples that are easy to copy and paste and make their API documentation a practical resource not only of valuable information but also of code that the developers can use anytime.
Using Too Much Technical Jargon
APIs are a highly complex software product, so it’s no wonder the documentation that accompanies them is sometimes challenging to understand.
If that is the case with yours, you might be making the mistake of including too much technical jargon in your API documentation.
It’s important to keep in mind that even though the product is complex, that doesn’t mean that the documentation needs to be convoluted and full of technical terms.
You should convey the information in plain language. That way, it’s accessible to a wider audience, not just experts who live and breathe code.
For example, your API documentation can reach audiences like:
- Stakeholders
- Technical writers
- Journalists
- Students
And even among developers, there can be significant differences in the level of experience and knowledge.
Therefore, if you don’t simplify the language you use in your documentation, you could potentially alienate large sections of your audience.
Of course, completely avoiding jargon isn’t realistic—some technical terms are unavoidable.
A solution for that is to include a glossary, like the one created by RapidAPI.
A glossary like that is a valuable resource for readers of any level of expertise and from any industry.
Having a glossary still doesn’t mean that you can use as much technical jargon as you want.
The text should be easy to read and understand without having to refer to a glossary for every other word.
However, it can be helpful to define those terms that are difficult to avoid in your documentation.
As the team from Altexsoft points out, the solution isn’t to cut out all the terminology—you should teach your readers the meaning behind it:
To simplify the language, you can’t just omit the necessary terminology for the domain or substitute in more friendly names. You have to teach the user the right language so they can participate in the conversation.
Using too much jargon can make your documentation a resource reserved only for a select few among your users.
In other words, jargon can make it unusable for anyone who isn’t well-versed in the industry language.
If you want to maximize the usefulness of your API documentation, avoid jargon where you can. And where you can’t, define and explain it.
Forgetting to Update the API Documentation
Like any other software product, APIs change frequently. Features are added or removed, code can change, etc. In short, APIs aren’t set in stone.
Neither should the related documentation be.
As APIs change over time, the documentation should reflect those changes. Not updating them can be a significant error.
Why? Because outdated API documentation can’t live up to its purpose of being the ultimate resource of information and support for users.
That can significantly impact your product’s reputation. If you don’t update the documentation regularly, you send out a message that you’re not reliable, and neither are your products.
If remembering to update your API documentation is challenging, you should create a release schedule that corresponds to the release schedule of your APIs’ new versions.
For example, Shopify releases new APIs every three months.
If you regularly update your APIs, that schedule can also be the schedule of your API documentation updates.
For instance, in Shopify’s example above, you can see that they released a new API version on January 1, 2023.
On the same date, they notified their users of all the changes in the product via their changelog.
There were nearly 40 changes in the new API version, each described in the changelog and in the documentation.
Shopify’s team included a link to the documentation article with more information about a particular change.
So, if a developer wanted to learn more about changes to the inventory states APIs, they could find the documentation about it right away, as it was updated the same day.
In short, as Shopify updated APIs, they also updated API documentation so it can remain a trustworthy source of information.
Having a reliable system for updating your API documentation and notifying your users about the changes is crucial for the usefulness of your resources.
Without that, your docs would quickly become obsolete.
Conclusion
API documentation is an indispensable companion for your APIs.
Without an excellent resource of information, your users will have a difficult time with your APIs. And if it comes to that, there are enough solutions out there that they can use instead.
However, you can prevent that by avoiding this most frequent mistakes we’ve examined in this article.
If you manage to do that, your API documentation will provide users with a great experience and ensure that your product and all of its elements are covered in detail.
