How to make API documentation and influence people

It doesn’t really matter whether you’re a seasoned developer, a fresh tech author, or a Product Owner dabbling in the IT field. You’re bound to have heard of APIs. No wonder. They have been a big thing for quite some time now, and they’re becoming even bigger as more and more companies realise how important it is to create your own APIs.

Yes, we’re talking business value. Actual business value.

But having APIs is not enough. You also need to explain how to use them properly, and how to adopt them to best suit the needs of specific services. And this is precisely where functional and modern API documentation comes in. The documentation should be clear and concise, should provide adequate examples, should guide the developers and allow them to move through the process as quickly and smoothly as possible.

How to prepare API documentation?

Using tools such as Swagger, some companies decide to go for API documentation that is automatically generated, for example, from annotations in the programming code.

“Automatically? So we don’t need to do anything, right?” you might ask.

Well, unfortunately, that’s not the case. Sure, the specifications will be generated automatically, but:

• Someone needs to prepare the annotations first.
• Someone still needs to create content to describe whatever was generated, explain the values, etc.
• An API reference is only one of the required elements.

You can’t really expect to have quality and robust API documentation with no effort. Automation is a nice start, but it only applies to a fraction of what you actually want to achieve.“Automatically? So we don’t need to do anything, right?” you might ask.

How to improve API documentation?

Firstly, you need to create a thorough content plan that covers all the necessary topics. A brief, end-to-end ‘Getting started’ tutorial on how to perform the most basic tasks with your API. A procedure guiding the developers through the authentication and authorisation process. An overview of possible status and error codes. A glossary containing terminology specific for your API. The list goes on.

And, naturally, you need to pay close attention to the core of your API documentation, namely, the reference listing all your resources and endpoints.

It is in this very section that the way in which you deliver content is of utmost importance. You may have wonderfully thought-out descriptions but if you present them in a poor manner, you’re sentencing developers to wander through documentation hell.

So how to enhance the user experience when it comes to API documentation? Well, there are numerous elements you can include. Let me list a selected few.

• Highlighting code syntax to make different types of parameters and values stand out
• Buttons that allow you to copy sample code
• Access to different tools. Many developers would benefit from something other than the popular JSON data format or language-agnostic cURL command-line utility
• Options to test the API right away, for example, a built-in console
• A conscious choice between 2-and 3-column layouts to match the type of content your API demands

Making API documentation modern, functional, and developer-friendly is not an easy task. You need to follow the current best practices not only for technical communication, but also for layout and design. If you’d like to find out how to make your API documentation top-notch and a real asset, feel free to contact us. We know the answers to all your queries. Alternatively, you can read more of our blog posts, such as this one on how API can be used as part of continuous deployment, or visit our API service page.