With 89% of developers using APIs in their work, API documentation is too important to take lightly.
And merely listing API references doesn’t cut it anymore—if you want your API to succeed, you’ll have to create more documents that explain its ins and outs.
In this article, we’ll explore how you can document your API to cover all its aspects, and learn about the different types of API documentation.
You’ll see that well-documented APIs don’t only make your users’ lives easier but can also help make your software more attractive to new customers.
We’ll start with an obligatory part of API documentation: code examples.
Code Recipes and Examples
You’ll have to dig deep to find an API document with no code examples.
This popular type of API documentation lets developers try out the API and see how it performs, making it the perfect opportunity for businesses to showcase their software solutions.
If you want another take on how code examples contribute to API documentation, you can think of them as recipes.
Like recipes, code examples are more of a guide than rules set in stone.
You can play around with them, add, delete, and modify the elements, and tinker with the code so that it fits your purpose the best.
Even developers have embraced the analogy and frequently use it to describe code samples.
For instance, the author of this repository uses food items to identify each React hook in the library.
Remember, Julia Child wouldn’t mind if you added another pinch of salt to a recipe, and API authors definitely don’t mind the users tweaking the code to utilize the API the best they can.
However, if you want developers to use your code, you have to make it accessible. That’s why most API documentation contains copy-pastable code.
You should also read: 6 Tips for Writing Great API Documentation
Shopify’s API documentation goes one step further and incorporates a handy Copy button into each code sample, shortening the already quick copy+paste process.
An additional reason why Shopify is an excellent role model for API code examples is that the authors have written a clear description of each code example, clarifying what it does.
No matter how intuitive your documentation is, people will still find ways to misinterpret it, resulting in less-than-ideal outcomes.
However, descriptions written clearly like these will ensure that the developers turn your examples into successful APIs.
So, besides listing the code ingredients, you should ensure that your API examples also include informative explanations—that’s how you create a complete API recipe.
In-Depth Topical Guides
Sometimes isolated pieces of code don’t do your product justice. To demonstrate the full potential of your API, you can create a topical guide, our next API documentation type.
Here we recommend to read: 7 Steps to Writing API Documentation.
In this section, we’ll analyze in-depth topical guides using an example from the documentation created by Stream, a company producing API for chat and activity feeds.
Simple overviews and API tours are a great way to attract potential customers. For instance, Stream offers an API tour that simulates the implementation of the solution.
All code is there; you just click buttons and watch the product take shape.
However, if you want to offer a deep dive into your API, you’ll need to cover its specialized areas.
Topical guides written for knowledgeable technical audiences show the ideas and conceptual aspects behind the API and its design.
While this type of API documentation requires more time to create, it can convince high-level customers of your API’s quality.
Stream begins the API topical guide by introducing the key concepts connected to the core element of the product, feed organization.
Now, an average dev doesn’t have to fully understand these concepts to implement the solution successfully, but an overview like this one can help paint the picture of the solution as a whole.
Similarly, you can use an in-depth topical guide to showcase the design and architecture behind your software, as Stream does here.
By reading the rest of the documentation, users can learn more about the details of the API.
All in all, in-depth topical guides may not be the most straightforward way to present an API, but they’re undoubtedly an asset that elevates the API documentation.
They allow you to create a narrative around your API and showcase all the intricacies behind it, demonstrating that you’ve scrupulously covered all the bases of the API.
Reference Guides
Reference guides are the most clear-cut type of API documentation.
They dissect the API and list all the information you need to work with it, such as details about methods, classes, functions, and more.
API references usually follow the same structure, which makes them relatively easy to compile. Common elements in reference guides cover:
- Functions
- Classes
- Parameters
- Return types
- Arguments
- Properties
And here’s what that looks like in practice, as seen in Square’s API reference guide.
As you can see, the Customers API is divided into parts concerning customer profiles, from listing customers to adding group memberships.
Each endpoint is prefaced with a concise description and supplemented with a code example. You can also see query parameters and response field information.
Although reference guides contain the crucial data you need to use APIs, you shouldn’t only rely on references to describe your API.
According to Gregory Koberger, the founder of ReadMe, reference guides should only be used as references, not as a substitute for API documentation altogether.
“You wouldn’t hand someone a thesaurus and expect them to learn English; in the same way you shouldn’t hand someone reference guides and expect them to learn how to use your API.”
To sum up, if you want to provide your users with a clear overview of your API, you should, by all means, create a reference guide.
Just don’t forget to supplement it with other document types to make your API even more comprehensible.
Support Forums
What if we told you that you can partially outsource your API documentation and enrich it with valuable input from real-life users?
That’s right; support forums are an excellent type of API documentation that lets you cover all the edge-cases without cluttering the primary documents.
If you described absolutely every scenario possible with your API, people would find your documents difficult to read and possibly abandon the product.
Enter support forums.
These digital spaces allow you to address the issues the users encounter and keep the knowledge publicly available.
We’ll now look at a Unity support forum question that has remained helpful for years after it was originally posted.
The original Unity documentation didn’t cover the API for SceneView class, so the user turned to the community for help.
Unity probably didn’t deem that specific aspect of the API significant enough to include it in the official documentation. Still, other forum users were able to assist with home-brewed solutions.
Besides relying on the community, some companies also encourage the support staff to answer the forum questions.
Either way, this sort of unstructured content lets you cover uncommon scenarios while keeping the actual documents clean.
If you want to extend the service life of your support forum, you should make the knowledge base searchable.
That way, you’ll prevent an influx of identical queries and provide the users with tried-and-true solutions.
Take a look at what one thankful Unity user said about the SceneView answer that we’ve just seen, three years after the answer was posted.
So, where there’s no room to elaborate an API aspect in official documents, support forums can fill in the gaps.
An additional benefit of support forums is that they can decrease the number of support tickets you receive, lowering your operational costs.
Instead of contacting support and waiting, users with issues can first check the support forum and find the solution already there.
After all, 90% of customers want an immediate response when they have a support question, so a support forum could keep you in your users’ good graces.
However, for best results, you should keep in mind the public nature of forums. Moderating the content will ensure that answers provided by the community members are relevant and helpful.
You can improve the user experience by periodically reviewing the content, flagging incorrect or inappropriate responses, and verifying the best answers.
API Marketing Materials
With so much effort you’ve put into creating quality API documentation, it would be a shame not to use your API for promotional purposes.
You can supplement the documents with API marketing materials.
These cover various types of content you produce to advertise your API, such as tutorials, press releases, infographics, and even social media posts.
Polishing your API references and code examples is certainly an excellent way to assure developers of your software product’s quality.
Doesn’t a neatly organized reference guide, like the Notion’s one that you see below, inspire confidence in the company?
Still, it’s worth noting that the decisions about purchasing software solutions are rarely made by a single person, so it isn’t sufficient to wow a developer with attractively described endpoints.
Instead, it’s usually a team of people in both non-technical and technical roles that makes purchasing decisions.
That’s why your API marketing materials need to appeal to audiences of different backgrounds.
Notion, the company whose reference guide we’ve just mentioned, knows the value of API marketing materials. They even run a Twitter account designated solely to the product’s API!
Unlike other types of API documentation, the purpose of marketing materials is to appeal to developers, product managers, and even end-users.
If you observe how Notion advertises the API, you’ll notice that they use plenty of visually appealing illustrations and plain language in their communication with customers.
The strategy extends further than Twitter; Notion also publishes release notes that reflect the constant improvements to the API.
Creating convincing supportive materials for your API requires additional effort, but you can streamline the process by employing a team of technical writers, designers, and copywriting experts.
We recommend to read: Why SaaS Startups Need Technical Writers.
We know; the people working directly with your API are probably more interested in error responses.
Still, investing in good marketing materials will help you attract more clients that will appreciate your actual API documents and put your product to good use.
Conclusion
Luckily for you, you don’t have to limit your API documentation to only one document type.
In fact, it might be better to combine all of them to ensure that no part of the API is left undocumented.
Whatever API document type you decide to create next, always remember to make the documentation informative, concise, and navigable. Archbee can help you with that!
That way, you’ll help developers use the API to its maximum capacity and grant your product many positive reviews.
