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 their 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 adapt them to best suit the specific needs of each service. And this is precisely where functional and modern API documentation comes in. The documentation should be clear and concise, provide adequate examples, and guide the developers, allowing them to move through the process as quickly and smoothly as possible.

How to prepare API documentation?

Using tools such as Swagger (OpenAPI), Postman, or Stoplight, 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.

Someone still needs to:

• Prepare the annotations first.
• Create descriptive content for whatever is generated
• Explain the values and usage
• Go beyond the reference with tutorials and guides

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.

How to improve API documentation?

Firstly, you need to create a thorough content plan that covers all the necessary topics, such as:

• A brief, end-to-end “Getting started” tutorial on how to perform the most basic tasks
• A procedure guiding developers through the authentication and authorisation process
• An overview of possible status and error codes
• A glossary containing terminology specific to your API

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

How to enhance the user experience?

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 incorrectly present them, you’re sentencing developers to wander through documentation hell.

What elements can enhance the developer experience? 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

Creating modern, functional, and developer-friendly API documentation 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 learn how to create top-notch API documentation that’s a real asset, please don’t hesitate 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.