The Blog

4 top resources to help you write great API documentation

Application programming interfaces (APIs) are valuable assets. But to exploit an API properly you need great documentation. Here’s why, and some resources to help you get your API documentation writing skills up to scratch.

APIs and the need for great API documentation

The human race is creating, consuming and updating more information than ever before, and APIs are everywhere. Successful APIs allow a product to spread (and develop revenue streams) in ways marketers hadn’t even dreamed of.

An organisation may have a lot riding on its API. But how does it make sure its APIs are successful in the big wide world?

Well, an API is basically a set of requirements that specify how one piece of software can communicate with another. So it doesn’t take much to realise that documentation plays a critical role in overall success. You can find data to back this up too. For example, in a 2013 survey by Programmable Web API users rated complete and accurate documentation as the most important factor in an API:

Important factors for APIs. Survey respondents ranked ‘Complete and accurate documentation’ as most important over all other factors.

Clearly, developers rely on documentation for their understanding. So it should come as no surprise that an API (and the product it supports) may thrive or fail on the strength of its documentation.

So without further ado, let’s highlight some resources to help us learn to do it right.

PURCHASE: ‘Learn API Technical Writing’ courses on Udemy

I’ve tried the first and it is very good, with clear explanations and follow-along examples. I haven’t tried the second yet, but I’m sure it is also very good.

These courses are reasonably priced. But if you’re holding back then perhaps a bargain-basement offer would clinch the deal for you? In that case, sign up to Udemy’s mailing list and keep your eyes peeled – they regularly offer dramatic discounts on all or many courses.

Over to you

Have you tried any of these resources? How did you get on with them? Any surprises? Can you suggest any other good resources in this niche?