API Documentation Guidelines

An API without a good user manual is next to useless. Developers would like a clear view of an API, code examples, detailed explanation of calls and parameters. And, they are not the only people visiting an API documentation portal. Many people with different roles are involved in API nowadays as this sphere has gained momentum. So, one should remember that when creating API documentation.
This article will give you the idea of what should be included in technical documentation for an API, and what you should pay attention to.

Overview

Try making your API manuals more user-friendly and approachable, as not only devs but also product managers, testers, support engineers can come across this documentation. You don’t need to oversimplify things, of course, but make sure you have a nice and clear introduction with an overview of the API in question.

Terminology

All terms should be explained thoroughly in any user manual, this is a common best practice. This is especially true for API documentation.
The more careful and precise you are with your terms, the easier it is for people to work with your technical documentation, and, therefore, the faster adoption goes.
Also, try avoiding jargon – there is no need to turn an API user manual into something overcomplicated and suitable for a bunch of pros only. Jargon has always been quite controversial in the techcomm community, refer to this article to learn more about using jargon in technical documentation.

Calls and Parameters

Don’t forget to mention and describe every call and parameter of your API. This is just as important as having all terms intact.
It doesn’t really matter how intuitive the UI is – devs are not almighty and all-knowing, so, try making this section as helpful as possible because this is one of the most important parts of any API documentation, its core.

Errors

A list of error codes would be great, but detailed error descriptions are better. Documentation exists to help people interact with a service correctly, and if something goes wrong, a user manual should be the first resort.
Remember that case deflection is one of the main functions of technical documentation. By the way, here’s the article on other possible case deflection techniques. Most of them are connected with technical writing, so, if you are a tech writer interested in saving time and resources, check it out.

Code Examples

Maximize your code examples’ presence in API documentation. This is always appreciated by developers and other readers. The more useful code samples you provide, the more valuable your API documentation gets. As simple as that.

On a Side Note: Design

No one wants their work to look sloppy and unprofessional, and that’s exactly what bad design can do to your technical documentation. Moreover, different user manuals require different approaches to design – industry best practices and a corporate style guide can help you figure out how your documentation should look.

Another thing is user experience. We want our user manuals to be effective and comfortable to work with. Design specifics directly influence UX along with the quality of writing itself. One of the main features of an API user manual is code. Since code samples are very common here, there should be a way to make them more readable. ClickHelp is one of help authoring tools that offer ready-to-use online documentation HTML templates and there’s one for API documentation, as well:

The dark blocks can be used for code samples to make help topics so much more readable!

Conclusion

API documentation is quite special. All these code samples and the overwhelming number of field-specific concepts… But, there are certain things you can do right now to make your API manual more appealing and effective. Following the guidelines given in this article, you can improve your API documentation and make case deflection and customer satisfaction go up.

Good luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices