How API docs became my silver lining – by Swapnil Ogale

An API (Application Programming Interface) is not a new thing by any stretch of the imagination. It has existed for quite some time (20 years and counting) and by any measure, it only grows in popularity every day. 

Practically every web product with an aspiration to be scalable and marketable has an API that allows other systems and products to talk to, build on, or integrate with the web product itself. There is also a general theory that APIs are only as good as their documentation. 

If people do not understand how to use the API, the API is pretty much useless. However, making it useful is easier said than done!

What is API (Application Programming Interface) documentation?

API documentation is a technical content deliverable, containing instructions on how to effectively use and integrate with an API. Check out this blog post from Swagger for more information!

This post is, however, not about how to create API documentation.

The sole objective of this post is to share how I got into API documentation, as well as what people aspiring to do so can do. This will add more range to their existing documentation skills. 

Starting out as a technical writer

While I have been a Technical Writer for close to 14 years, most of my earlier projects had been around documenting product content, such as user guides, online help or process and procedural content such as work instructions, user manuals etc. 

For the last half a dozen or so years, I was fascinated by stories of writers dipping their toes into the exciting world of API documentation and it had become sort of a personal goal to learn as much as I could about this. As a result, I pursued various resources to understand how APIs worked and how someone went about documenting them. 

Getting started with API docs

Mid 2015 and I had just parted with the organisation I was working for over 18 months on not-so-favourable terms. I had no other work lined up and had no idea of where I was going next. The only silver lining was a 1-day course I had signed up for in Sydney, immediately the week after I finished up.

Sarah Maddox, a tech writer friend of mine, was conducting a 1-day workshop on API documentation at Google, Sydney. This was my first foray into the world of API documentation. The workshop was excellent, practical, and full of useful examples. It provided me with enough motivation to continue learning about how APIs worked, about the technology involved, and how to best document APIs.

I had some free time (more out of circumstance than careful planning), so I signed up for a few online courses with Udemy, particularly designed by Peter Gruenbaum.

Also, Tom Johnson’s legendary work (almost a textbook) in this space, an online course on documenting APIs, still stands as one of the best starting points to learn about API docs.

API Docs v2.0

While I had attended Sarah’s workshop in 2015 and devoured some of the online courses around API documentation with great eagerness, it wasn’t until 2018 that I got to actually work with real-life API projects. 

Where do I begin with this story? Oh yes, I remember that week clearly. 

I was replacing a technical writer who was working on an energy project. We shared an equivalent of 3 and a half days of handover time. Along with 2 user guides and an online help component, she was also working on delivering 2 API guides (separate APIs for the energy project). 

Her first act of daredevilry was to hand me these API guides and quickly explain how the APIs worked, and provide contact details of the developers working on the APIs. 

From week 2, I was pretty much thrown in the deep end of documenting two full blown API guides! Just add to that extremely tight deadlines on these deliverables, and it had all the makings of a great thriller. Thankfully, the developers working on the APIs offered a lot of support, and helped me deliver the API documentation in a timely and efficient manner. 

After this experience, I felt reasonably confident in tackling projects involving APIs, and luckily I was assigned to a couple of projects that revolved around APIs. 

These 2 projects really tested my documentation skills, but the effort came through in the end when the project launched and our business users appreciated the level of detail and completeness of the API documentation. By a strange turn of events, the API documentation also became the driver for development efforts on the project. 

Towards the end of the projects, I also got an opportunity to help the API integration team working on the developer portal (another level up from core API docs) to design, test and write content for the developer portal.

APIs, SDKs, oh my!

So, here’s the thing. Once you get started in this wonderful, challenging and rewarding space, you end up getting more of these projects. Last year, I was contacted by a startup founder to get some help on their SDK documentation. 

For information on how SDKs are different from APIs, see this article.

While there was not a lot of new content to be created, it involved reviewing and editing the developer-written content to make it easier to read. Using some of the other technical writing and information architecture skills, I was also able to assist with organising the information in a logical manner. 

As a method of giving feedback, the project manager really appreciated the work put in, and the love given to this piece of documentation. This may lead to possible other work from this organisation.

From multiple to a single endpoint

What started off with documenting REST API endpoints, evolved into documenting developer portals using a single endpoint with something like GraphQL. 

It is a bit of a learning curve, in terms of terminology and operations, but end of the day, it all comes down to one thing: making technical content clearer and easier to understand for a wide audience.

Final remarks

While I was certainly aiming to work with APIs, I feel I can attribute some of my current involvement to a combination of timing, learning from the right resources, and being open to new technologies and working with developers using different tech stacks. 

Here's a quick summary of what I've learned about APIs:

• API documentation offers an exciting and challenging space for technical writers, and there is a growing demand for good quality API doc writers. 
• To get started, you could earn more experience by helping out open source projects that need API documentation. 
• Google’s Season of Docs offers a good starting point for technical writers who wish to get exposure to API docs.