4 top resources to help you write great API documentation

Eric WestonTechnical communicationLeave a Comment

Writing 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:

API documentation: api-survey-important-factors-600x375

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.

API documentation resources for writers

FREE: MadCap recorded webinar ‘API ABCs’

API ABCs

  • Covers some good detail and interesting examples
  • Touches on both SOAP and REST APIs

There is a link on the page from which you can simply download a PDF version of slides from the webinar. But I strongly recommend you watch the recorded webinar:

  1. Open the page at API ABCs.
  2. Scroll down to the form at the bottom of the page and give MadCap your details. They will then email a link to you.
  3. Check your email and open the link. You can then watch the recording in your web browser or follow another link to download it to your computer as an MP4 file.
Notes about the webinar recording:
  • The recording is 1 hour long, including Q&A. Jump to 2m 50s if you want to skip the introductory fluff.
  • There were some technical problems during the recording, but it is worth persevering. There is no audio between 30m 08s and 31m 47s, and again between 41m 15s and 42m 40s.

FREE: REST API course on the ‘I’d Rather Be Writing’ blog

Tom Johnson created a great REST API course on his blog http://idratherbewriting.com/restapicourse/

He covers topics in good detail and uses a proper ‘hands-on’ example throughout so you can follow along and really get the hang of it.

PURCHASE: ‘Learn API Technical Writing’ courses on Udemy

Online learning marketplace Udemy has two very apt courses:

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?