How to Write Great API Documentation Every Time

What goes into creating the best API documentation is a contentious subject.

Most developers have their own opinions on what should and shouldn’t go in to API documentation. It’s rare for everyone to agree.

Everything from what you put in it to how things are laid out will affect the experience for your customers. That’s why getting it right is so crucial.

Fail to get it right and you risk deterring prospects from using your API because they don’t understand how things work, or worse — a slew of support tickets that take up everyone’s time.

I spoke to Cronofy’s development team to find out more about how they approach writing ours.

Consider it when developing a new feature

Photo by rawpixel on Unsplash

“Not considering your API documentation as part of your product is usually the root cause of bad documentation,” says Stephen, our Senior Developer.

“The API documentation is the first thing we consider whenever we are developing a new feature. We often have long discussions about the correct terminology for each property, trying to avoid ambiguity wherever we can.”

This is important to ensure that it’s as simple and easy-to-understand as possible.

The vaguer your description of a feature or element of it is, the more likely it is to confuse customers and the more support requests you’re likely to get.

“Not considering your API documentation as part of your product is usually the root cause of bad documentation.” — Stephen, Senior Developer, Cronofy

Factoring in the documentation while building the new feature also gives you time to work through any issues. Customers can give you feedback during Alpha and Beta phases, further allowing you to refine the docs before it goes live.

Stephen continued by saying this: “The API design does change during our development phase. Often when we write SDK and format documentation we spot things we’d like to tidy up before making things public as we never change our public API.

“Another key aspect of this is our Alpha and Beta phases where we rely on our customers to let us know how fit for purpose the documentation is.”

When the product does go live, you can be sure that you’ve worked out most of the kinks and it will help your users get to grips with the new feature.

Have clear examples

Photo by rawpixel on Unsplash

“With the most complex API methods giving examples and extra supporting documentation is essential. If you don’t do this you’ll often be paying this back though additional support requests,” says Garry our CTO.

“With the most complex API methods giving examples and extra supporting documentation is essential.” — Garry, CTO, Cronofy

“Many of our endpoints have optional parameters, but there’s a common set that are required and optional ones we recommend are set. So I start with a request that reflects those best practices, and the kind of response that can be expected to be received in return.

“This provides a context around which to explain all possible parameters, what their potential values are, what their defaults are if they aren’t provided, and finally what that all means together.”

By starting with an example, you put an image in people’s heads. This image helps with their understanding. Customers and prospects will understand your product/feature much faster with an explanation like this.

Common usage examples also incorporate storytelling to show your users what they could create.

The more context you provide for your customers, they more likely they are to understand the feature and be excited about adding it to their software.

Usability and consistency are key

Photo by NESA by Makers on Unsplash“Simple things like making the documentation available offline or adding deep linking really help.” — Stephen, Senior Developer

Usability is a must in all aspects of software development, and API documentation is no different.

“Key things like usability, consistency, and features are often overlooked. Simple things like making the documentation available offline or adding deep linking really help,” says Stephen.

“My pet peeves are when you have parts of the documentation which contradict themselves or leave things as ambiguous. It doesn’t matter if you know what the behaviour is, write it down so others do too.

“For example, if the definition of a property states a value must be greater than zero but the validation states the value must be positive, the implementer must make a decision if 0 is a valid input.”

Don’t rely on tools to generate it for you

Photo by Tyler Franta on Unsplash

It’s easy to want to rely on tools to do things for you, but if you want to create the best experience for your users, this isn’t the best way to go.

“You see things such as a thing having a field named ‘comment’ and a description of ‘the thing’s comment’. This doesn’t tell you what type it is, or could be, though you might guess it’s a string. Nor does it tell you the format of that string. It could be plain text, HTML, Markdown, or something else. It doesn’t tell you how long that string may be so you can cleanse your requests and size your database field appropriately. It doesn’t tell you whether it’s ASCII, UTF-8, or something else so you can use the correct type of encoding,” says Garry.

“There’s just so much you then have to work out yourself as the developer, and that compounds over every developer that uses that API. So what saves the publisher a few hours costs their customers hours each.”

“It’s easy to want to rely on automation tools to fix things for you, but if you want to create the best experience for your users, this isn’t the best way to go.” — Garry, CTO

Sometimes the time and cost savings for you aren’t worth it when you consider the end-user experience. And really, isn’t how your customers feel the most important thing? If they don’t like what you’re doing, they’re less likely to recommend you to their network, which means less custom for you.

A great experience, on the other hand, means they’re more likely to recommend you to their network, further increasing your influence, attracting new customers, and giving you more money to build more features.

Conclusion

Photo by Rishi Deep on Unsplash

What makes great API documentation may be a contentious subject, but for the most part, the basics are pretty simple:

• Consider it as part of your feature, not an after thought
• Have clear examples
• Be consistent
• Think about the user experience
• Don’t rely on tools to generate it for you

All these elements work together to ensure that your customers fully understand what they can build when they use your API. This means they’re more likely to use it to its fullest.

A well-documented API also means you’re less likely to get frequent support tickets from customers who don’t understand how X or Y feature works or why something doesn’t do what they want it to.

Taking the extra time to put together a consistent, well-considered documentation will pay dividends in the long run.

What do you think makes for great API documentation?

Try our API

If you’re a developer and want to see how easy it is to add two-way calendar sync to your software, head over to our website where you could be making your first API call in minutes.

Not a developer? Connect your calendar to your favorite apps — including Trello, Slack, and Evernote — using our free Calendar Connectors.

How to Write Great API Documentation Every Time was originally published in Hacker Noon on Medium, where people are continuing the conversation by highlighting and responding to this story.