Pros and Cons of Different Types of API Documentation

In a perfect world, every developer would have the time to read your documentation front to back and use your API to its fullest potential.

However, that’s rarely the case, which is why you have to carefully pick and choose how you present your API throughout different types of documentation.

Each of the types (that we’ve covered here) comes with its own advantages and limitations, and it’s up to you to decide if you want to put more focus on, say, the topical guide or code samples.

In this article, we’ll lay out the pros and cons of different types of documentation that accompany APIs so that you can decide how to present the value of your API to the world.

We’ll start with the most commonly used type of API documentation, the code examples.

Code Recipes and Examples

Have you ever assembled a piece of furniture by skipping the introduction and going straight to illustrations that show you directly how you can put the cabinet together?

If you have, then you understand the point of code recipes and examples.

These are ready-to-use code snippets that allow for a straightforward implementation of APIs.

We’ll now see what makes them so convenient and also in what case it’s better to reduce the use of pastable code.

Pros

The best thing about code examples is that they provide insight into your API in an instant.

Let’s say a developer wanted to program a script that schedules sending Slack messages.

Rather than coding from scratch, they could visit the Slack API documentation, find the function they’re looking for, and paste it directly into their code base to see how it works.

Essentially, code recipes and examples help developers start using an API within minutes.

They provide a starting point from which developers can build their apps without spending time setting up the foundations first.

So, if you want to make sure your API docs are as accessible as possible, code examples are a vital element to include. We have for you a quick API documentation checklist you should check!

Cons

While recipes and examples are extremely useful for getting the code up and running quickly, there is a strong case against relying too much on copy-pastable code to build products.

Josef Cruz, a JavaScript expert, recognizes the benefits of ready-made code, but still discourages the devs from the practice because it can promote using only surface-level knowledge.

In other words, if the devs copy and paste the samples without thinking about them, they may not understand the underlying cause of the problems that may arise.

Here’s how Cruz sees the issue.

The problem is that the copied code is not always understood by the person who copied it. The application works. The developer does not wonder why it is.

It’s worth noting that there’s nothing inherently wrong with copied code recipes.

However, basing the entire code base on somebody else’s code could reduce the overall quality of the code, which is why it’s best to use code recipes in moderation.

Reference Guides

Reference guides list all functions, classes, parameters, and all other elements of an API that show developers how to use the API.

Such an abundance of information can be a double-edged sword—all the details about the API are there, but how usable are they, really?

Pros

The primary reason why reference guides are always included in API documentation is that they are the ultimate tool for exploring the API.

References do more than show developers what’s possible with the API—they can also be used as knowledge bases because they contain all the information needed for working with the API.

You can see an example of this in the screenshot below, in which Airtable’s reference guide outlines all actions the devs can take with table records, and what’s needed to do so.

However, another significant benefit of including a reference guide in your API docs lies in the convenience of making one.

There’s no need to type the guides by hand because there are tools you can use to generate references automatically, such as Archbee.

Due to the fact that it's a complete product documentation platform, Archbee lets you generate API references automatically.

You only have to upload your API definition file, and the platform takes care of the rest. Of course, you’ll get better results if your code is well-documented within the code base.

The reference generator feature is especially beneficial if you have an API you’re constantly upgrading, because you can effortlessly ensure that your users can always access the latest version of the references—it’s a win-win situation for both sides.

Cons

Remember when we said that reference guides provide all the details about the API?

Well, getting too caught up in the intricacies of the API may not be the most efficient use of a developer’s time.

Although some devs, like the one from the screenshot below, get drawn to reading entire reference guides, you should ask yourself if that’s really beneficial to your project.

Knowing your way around the API you’re working with is indisputably helpful, but keep in mind that sometimes reading about too many aspects of the API makes it hard to see the forest for the trees.

In other words, focusing on individual references might make it harder to see the full context of the API as a whole.

Topical Guides

Reference guides are a handy way to demonstrate how individual elements of the API work.

But if you want to paint a bigger picture of your API, then you need a topical guide, which offers a look behind the design and the philosophy of the API.

Pros

Developers need more than just a list of classes to use your API.

So, the biggest benefit of including a topical guide among your docs is that it provides you with an opportunity to truly dive deeper into the infrastructure of your API.

As the term suggests, these guides are divided into topics where you can write about the main functionalities that your API provides.

Let’s see what a topical guide can look like in practice. Below, you can see an excerpt from the topical guide for SwiftUI, Apple’s framework for building user interfaces.

On the left, there’s a list of topics. When you choose one, you’ll get its detailed overview.

Unlike concise auto-generated reference guides, topical guides supply readers with in-depth contextual information—they almost verge on storytelling.

So, if a dev was on the fence about using your API, a well-written topical guide could convince them to try it out.

Cons

What happens when you describe your API’s key concepts, authorization, rate limits, models, methods, and more in one section of product documentation?

A possible information overload, that’s what.

Such a large sum of material can easily become overwhelming, which is a drawback of topical guides to look out for.

Some API providers are, fortunately, aware of how demanding topical guides can be to get through, especially for the devs that are not that well versed in the API yet.

That’s why, for instance, the React topical guide includes a disclaimer that encourages users to study additional resources and then return to the docs when they’re equipped with more knowledge.

You don’t have to shorten your topical guide, though. You should feel free to approach the docs thoroughly, as long as you keep the language comprehensible.

Remember that developers are good at coding, not necessarily at writing guides, so it could be wise to have an API technical writer on board.

Support Forums

Developer community forums or support forums, whatever you call them, can be a helpful extension of your API documentation.

These spaces dedicated to discussing the API allow you and other developers to cover additional scenarios and solutions regarding the API, saving your support team time and money.

Still, unless you take a few extra steps in maintaining the forum, your support forum may not be as helpful. Let’s see why and how.

Pros

The biggest advantage of API support forums is that they reduce your support load.

Instead of filling out support tickets, developers with questions about the API can talk with other community members that have already encountered the same problems.

Support forums come in various forms: some APIs have their own support centers, while others provide links to external forums, such as GitHub and Stack Overflow.

React, the framework we’ve mentioned above, even has a page that refers developers to the most appropriate forums depending on the nature of their questions.

By setting up a support forum for your API, you’re practically outsourcing support at no extra cost while also strengthening the community of the API users.

Therefore, when devs encounter edge cases that haven’t been described in reference and topical guides, they won’t have to stop using the API—they can look up how other developers have overcome the issue.

Cons

If completely free API support via forums sounds too good to be true, that’s because it is.

To make your support forum truly helpful, you have to ensure that it isn’t just a graveyard of unanswered questions, which looks something like this.

Relying on community members to keep the forum informative shouldn’t be your go-to strategy.

Instead, it’s better to ask the original developers to regularly visit the forum and contribute to it.

For instance, this thread about CFS socket APIs on Apple’s forum has answers written by a developer working at the company.

To sum up, if you aim to create an informative support forum, you’ll have to ask your devs to moderate the discussions and participate when needed.

Marketing Materials

Marketing materials include all content created to promote your API to potential customers.

These can include written content, brochures, illustrations, API client reviews, highlighted security certificates, and anything else you can think of that shows what your API does at a glance.

Of course, marketing materials can’t replace the actual API documentation, but that’s not a problem because their purpose isn’t to educate—it’s to persuade people to use the API.

Pros

You could have the best API there is, detailed topical and reference guides, and still struggle with getting clients to use it. If that’s the case, you need to create API marketing materials. Here are some API documentation best practices you can follow for better documentation.

The advantage of such materials is that they don’t only target software developers.

After all, the devs aren’t the only decision-makers your API needs to impress.

You also have to think about product managers or non-technical roles that have a say in the choice of the tools used for building the product.

Because of that, a significant portion of API marketing materials uses straightforward language and lay terms, as you can see in this example of marketing copy created by Cronofy, a calendar API.

If you write the marketing materials well, you’ll be able to explain the API to non-tech roles and increase the chances of your API’s adoption.

So, go ahead and hire content strategists, writers, and designers to help you portray your API in the best way possible.

Cons

Since marketing materials are used to convince the general public about the usefulness of your API, you can’t get too technical in them, which makes the materials insufficient for developers interested in how the API works under the hood.

Take a look at how Stream, a chat and activity API, presents their solution.

From this concise description, users can learn that the Stream API can help them manage feeds within their apps.

However, developers who want to learn more about how the API works still have to refer to topical and reference guides.

To put this differently, marketing materials can boost your sales, but you should remain mindful of their limitations in terms of educating readers about the API.

Conclusion

Some of these documentation types go deep into technical details, while others give a brief overview of what your API can accomplish. Fortunately, you don’t have to choose just one type of API documentation and stick to it.

You can—and should—combine multiple forms of docs to create an all-encompassing knowledge base that educates all types of users about your API.

So, go ahead and create the supporting documentation. Your API deserves it, and your users will be grateful.

We hope that our approach with pros and cons of different types of API documentation helped you on your journey!

‍

FAQ