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

"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. 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.

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

Stephen continued by saying this: "The API design does change during our development phase and 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 rest assured 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

"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 Shutler our CTO.

"With the most complex API methods giving examples and extra supporting documentation is essential."
Garry Shutler, CTO

"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 default 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 with the new feature. 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

"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

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. "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 Shutler. "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 Shutler, 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.

What do you think makes for great API documentation? Let us know on Twitter!

We originally published this post on Hacker Noon.