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 to develop and hone your API documentation writing skills.
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:
And Postman’s 2020 State of the API Report states:
…the number one obstacle to consuming APIs: lack of documentation (which also led other factors by a wide margin)…
2020 State of the API Report, Additional Insights, https://www.postman.com/state-of-api/
The four most important factors individuals consider before integration with an API are reliability (71.6%), security (71.0%), performance (70.9%), and documentation (70.3%).
2020 State of the API Report, Additional Insights, https://www.postman.com/state-of-api/
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, here are some resources to help us learn to do it right.
Boost your understanding
Free resource: ‘An introduction to APIs’ (course and ebook)
A course by Zapier, which you can also download as an ebook (PDF and EPUB):
Free resource: ‘Moving into API documentation writing’ (slides)
Slides by technical communications specialist Ellis Pratt of CherryLeaf:
Free resource: ‘The ABCs of APIs’ (video)
A recorded webinar, hosted on the MadCap Software website (the learning material is general and not specific to their software):
- Focuses on both SOAP and REST APIs.
- Covers some good detail and interesting examples.
If you click the DOWNLOAD WEBINAR ASSETS link on the page then you can download a PDF version of webinar slides. But I strongly recommend you watch the recorded webinar.
Note: 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 resource: ‘API types’ (slides)
Slides by writer Sarah Maddox, which she adapted from her Ffeathers blog post:
Develop your skills
Free resource: ‘The Best API Documentation’ (blog post)
A blog post by developer Bradford Fults:
- A nice summary of tips and of pitfalls to avoid.
Free resource: ‘Documenting APIs’ (course)
A course by technical writer Tom Johnson, on his blog I’d rather be Writing:
- Focuses on REST APIs in particular.
- A very informative and practical guide.
Tom 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.
Paid resources: ‘Learn API Technical Writing’ (courses)
Some very apt courses on Udemy, the online learning marketplace:
- Clear explanations and examples that are easy to follow.
- Builds the foundation for you to understand data formats that are important for APIs.
- Clear explanations and examples that are easy to follow.
- Builds on the first course and focuses on REST APIs and reference documentation.
- Builds on the first two courses to help you write conceptual documentation, such as overviews, getting started sections, and tutorials.
I bought the first two courses for myself. I completed the first and can vouch for it as an instructive, well-paced and high quality course. I feel confident that the other two will be just as good.
These courses are also very affordable. But if find yourself holding back then perhaps a bargain-basement offer would clinch the deal for you? In that case, keep your eyes peeled (and maybe sign up to Udemy’s mailing list) — they often offer dramatic discounts on courses.
Get a head start
Paid resource: ‘API Documentation Template’ (template pack)
A Microsoft Word template pack from ihearttechnicalwriting.com:
I can’t vouch for this resource as I haven’t tried it myself. But, it seems like it could be worthy of your consideration. After all, it can be great to have something tangible to start with rather than a blank page — and you could copy the template contents out to your preferred writing tool if Word is not your thing*.
Note: *Software for writing technical documentation
Microsoft Word continues to be pressed into service for technical documentation far too often. It really isn’t ideal for this purpose — for all its many features, it is really still just a word processor. It is built for people to create relatively simple one-time documents — not to maintain a suite of inter-related and ever-changing publications in a range of output formats.
I won’t delve into the in’s and out’s and alternatives here. But for an excellent zero-cost alternative see:
- Asciidoc — a plain text markup language and toolchain that is built for technical documentation. It is very easy to learn, easy to manage, and easy to transform into HTML5, PDF and other output formats.
- AsciidocFX — a free document editor that makes it so easy to get started with Asciidoc that there’s really no excuse not to give it a try!
These and related tools are ideal for a ‘docs as code’ approach, which is great but makes particular sense in the context of APIs (and software development in general).
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?
This article is a substantial rewrite of an earlier version that I first published on 2015/07/27 under the title “4 top resources to help you write great API documentation”.