Most Frequent Mistakes to Avoid in API Documentation

Davor is a content marketing expert who loves writing about project management, productivity, and remote work.

In this article, we’ll warn you about the most frequent API documentation mistakes and how to make sure you don’t make them.

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:

Peter Hilton about why code-generated documentation is a mistake
Illustration: / Data: Hilton

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:

  1. API Documentation Best Practices You Can Follow
  2. 6 Tips for Writing Great API Documentation

For example, below, you can see an example of documentation generated by Swagger, one of the best-known tools for that purpose.

Documenting Your Existing APIs: API Documentation Made Easy with OpenAPI & Swagger
Source: Swagger

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:

Instagram Graph API documentation
Source: Facebook

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.

Getting started guide about how to get a user access token
Source: Facebook

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.

API documentation tool

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.

Response Codes on Twitter
Source: Twitter

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.

Installing with OAuth on Slack
Source: Slack

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:

API documentation on Mozilla
Source: Mozilla

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.

HTTP request methods on Mozilla
Source: Mozilla

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.

Tom Johnson about code
Illustration: / Data: I’d Rather Be Writing

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.

Developers consider examples the number one feature they look for in API documentation
Source: SmartBear

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.

Mailchimp provides code examples for their APIs
Source: Mailchimp

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.

API Glossary: Glossary of API Terms & Programming Acronyms
Source: 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.

Shopify releases new APIs every three months
Source: Shopify

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 Developer Changelog
Source: Shopify

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.

Manage inventory quantities and states
Source: Shopify

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.


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.


Frequently Asked Questions

What are the drawbacks of relying totally on API documentation generated from code?
Expand FAQ
API documentation generated from code can't provide users with comprehensive information about the API such as what it does, how it works, its benefits, and best practices for using it to its full potential. It often lacks practical examples and doesn't explain possible error messages.
Why is it important to include important sections in API documentation?
Expand Button
Including important sections in API documentation is crucial as users expect to find all the information they need to work with the APIs successfully. Important sections include error messages, authentication processes, and HTTP requests. If these are missing, users may find the resource insufficient and start looking for other solutions.
Why should API documentation provide code examples?
Expand Button
Code examples in API documentation are essential for showing what the APIs are capable of as soon as possible. They simplify the implementation by demonstrating how the APIs work without developers having to figure it out themselves. Code examples are considered the most important API documentation feature by developers.
How can using too much technical jargon in API documentation be problematic?
Expand Button
Using too much technical jargon makes API documentation hard to understand for anyone who isn't well-versed in the industry language. It can potentially alienate large sections of the audience. Jargon should be avoided where possible and where it can't, it should be defined and explained.
Why is it important to regularly update API documentation?
Expand Button
As APIs change over time, the documentation should reflect those changes to remain a reliable source of information. Outdated documentation can negatively impact the product's reputation. Regular updates should ideally correspond to the release schedule of the APIs' new versions.

📖 Table of contents

Answer questions instantly

Create and share documentation that answers questions instantly with Gen AI

Discover Archbee

Receive documentation and technical writing tips & trends — our newsletter

Join 5000+ people from around the world that receive a monthly edition of the Archbee Blog Newsletter.