Tuesday, 1 September 2015

The Basics - How to Document APIs

An occasional series looking at best practice for common documentation tasks and situations. 


This blog is written for several purposes. Some of the articles are the amalgamation of my experiences that I'd like to pass on to anyone who is interested, and some are articles that help me clarify and explain my thoughts on certain topics within the realm of Agile Technical Writing.  These cover the majority of the posts here on www.agiledocumentation.co.uk.

But occasionally, I use this blog as an auto-didactic tool when I'm learning about something new.  It helps me to organise and manage the new information and connections; as the old saw goes, "if you want to learn something, try teaching someone else".  The subject of documenting APIs is a case in point.

API documentation may or may not come under the heading of "The Basics", depending on what area you write about.  My background is software documentation, so being able to grasp the basics of API documentation is a requirement for me.  In fairness, the basics are easy to pick up, because the principles are the same for all technical documentation (concision, clarity, accuracy, correct audience target) and the practise is uncomplicated (access, inputs, outputs, effects). However, my experience has primarily been with SOAP web service APIs, which is only one of a number of types of web service APIs, which in turn are only one of a number of types of API.  So I decided to brush up on some of the API documentation knowledge that I'm missing, and was planning on writing an article covering the basics that I learnt.

Normally, the process of learning starts with Wikipedia (because its technical articles are normally pretty accurate on the basics and it often has a useful list of links for further research) and moves on to Googling overviews, tutorials, etc.  This process can last anything from a couple of hours to a couple of weeks depending on what I already know, and how complicated the source material is to get my head around.  Then I write about what I've learnt.  Doubtless this is familiar to anyone who writes technical documentation for a living.

However, in the case of API documentation I can't do the subject justice when there is a better resource for my loyal readers, and it's Sarah Maddox's blog.  Sarah is a Technical Writer for Atlassian and, as I've come to realise, a doyen of API documentation.  I'm not too proud to realise that sometimes there is someone who just knows a lot more than me, and communicates it very well, and in this case Sarah is that maven.  Start here for a good overview of API types, and then review her API category for more great articles.

In addition, there's a good article from the Parse blog on this subject, and anyone that uses the phrase "carefully crafted with love" to describe their documentation gets a respectful nod from me.  You can also find some great examples of API documentation here and here.

If in the future I find an arcane area of API documentation that could use some elucidation then I'll apply myself to that task, but otherwise I'll leave API documentation articles to the experts like Sarah.....