#apidocumentation

When talking about APIs, the most common reaction from the Tech Writers I interact with (in the virtual or real world) is a resounding “ugh!”. There are also a few who say it is “easy” because there’s “nothing to write!”

Both reactions may be a tad misguided.

When Tech Writing was my full-time occupation, I was a bit wary of APIs in the beginning, sure, but learned to take them in my stride. A writer’s perception back then (about 12-13 yrs back) usually was - “chunky, ugly code”, “boring”, “beyond redemption!”, the most absurd - “too technical”, and yet again - “nothing to write”. The seasoned writers would recommend one to just work as best as you can to fit it in your documentation template - ensure that it carries the company branding and blends in with the rest of the documentation, that’s all.

It wasn't made any easier by the engineers, who would often snootily scoff if the writers had any questions (considered too obvious), or would have suggestions for improvement (parameter names or comments). They seemed to be in a hurry to somehow get done with it. Was it because they thought they wrote such good code that the documentation was redundant? Or, were they too possessive to share their work-of-art? Or, was it because they found it as “boring” or “beyond redemption” as their writer peers would? They would generally want the writers to blindly follow their instructions; After all, the coders know their code best, not the writers. Is there really a point in any discussion?

All of us inhabited our own islands and our rifts would make the documentation suffer. Very few SDKs we had written back in time, or had access to, were of any use. The cause could be:

Unfriendly language

Incomplete explanations

Useless parameter definitions, etc. 

Over the course of time, things have changed for the better. Open source has somewhere made us more open-minded about feedback. We manage to have constructive debate on the documentation styles. However, the mode and representation haven’t changed as widely as it should have.

Let's face it - we can always do better. We can write better documentation, the UI can always be way better than it is, and of course, the code can be written better. The question still lingers - why APIs? Why document APIs?

If we think of the potential - it is enormous. User experience is paramount. Let's focus on mobile devices alone, of what we provide - the range of apps - eCommerce, games, fitness programs, chat, and so on. If we open the APIs out, as many have, the impact is huge! The various collaborations have yielded such amazing results that reflect in the way the documentation tools have evolved too. One is allowed to be “inspired” to build similar/better apps (not plagiarize) that improve user experience, rework smaller segments of an existing app to make it  better. The community communicates, innovates more, and not surprisingly, a lot of these collaborators who are spread across the globe never have met once!

If we open our APIs out, there’s no bigger hindrance than unfathomable reams of API accompanied by crappy API documentation or none! R.I.P growth and innovation.

Why take baby steps here when the impact could be so great? And that was my philosophy when I started consulting with one of our largest eCommerce companies on their seller API documentation.

The frustrations of collaborating with the various departments within the company aside, I am trying to avoid taking baby steps. I am now trying to take huge leaps to make it easier for our sellers to build what they need over our platform. It is still W.I.P, but the good news... it is way better than what was there, and is only going to improve as we move forward! That can never happen if I try to squeeze in API documentation into the traditional, decades old documentation methodologies. Instead, I am re-skilling.

My approach? Clarity.

Purpose - why are we documenting these APIs? Who is it for - know your audience.

Precision - if I didn't know much about the domain, if I were located seven seas away, could I do something useful based on the information in the document alone?

Implementation - how am I going to distribute the docs? Is maintenance easy in my absence?

Of these three, the 1st two are probably hard to achieve, but crucial as they decide the direction your documentation will take. The third one is a bit tedious (perhaps?) given that it involves choosing from the many available options/budgets, etc. So, while approximations are acceptable in real, day-to-day life, it is always good to be precise when giving instructions for someone to follow.

Flexible API Documentation with ApiDoc (http://apidoc.codeplex.com)

What is ApiDoc

ApiDoc is a tool for creating a set of technical API documents to help developers…