Recent Comments

Search results

STC Intercom Issue Entirely Dedicated to API Documentation

The September issue of the STC Intercom is entirely dedicated to API documentation (if you don't have access to STC, go to this alternative). I had the opportunity to act as guest editor for this issue. As guest editor, I helped select the topics, find the writers, and did some editing on the articles. I also wrote a foreword to the articles. It was a pretty cool experience altogether.

This issue of the STC Intercom is entirely dedicated to API documentation.

Six articles appeared in print, and for lack of space, another four appeared only in the online edition. That's 10 articles altogether.

Here's the list of articles:

(Note that you have to be an STC member to access the articles. Sep 15, 2014 Update: Someone put the issue on Dropbox here.)

The author shares some of the lessons she learned working as an API writer, including terminology, working the development team, using the technology, learning about class libraries, and understanding stakeholders and users.

One of the biggest challenges technical writers have in writing documentation is learning
to read code. How much programming is needed? The author explains how to pick a programming language and a project, how to write good code samples, and provides further resources.

Over the years the IT industry has seen a significant growth in APIs that are available as free and paid services. Clearly, it is imperative to have good API documentation for developers to be able to use these APIs to develop their application, and there is a need for good documentation tools to create good API documentation.

One of the most common types of APIs that technical communicators document are REST APIs. REST APIs facilitate the interaction of client-server technology: a client sends a request to the server and, after some processing, the server returns a response to the client.

Exclusive attitudes from engineers come with the territory. The feeling of disrespect seems to stem from a natural effect of the engineers being the source of knowledge and the technical writers being the pursuant of that knowledge.

My foreword

Here's the foreword I wrote. This appears in the beginning pages of the issue.

From the Guest Editor

For the first eight years of my technical writing career, I wrote GUI-based end-user documentation. By GUI-based documentation, I mean the kind of documentation that includes a user interface where users can interact by clicking buttons, selecting options from lists, browsing from tab to tab, and so on.

Writing GUI-based documentation was all right. I felt I could figure out any application in a short amount of time. By mere trial and error, I could learn the logic and workflow and write the help topics.

One day, my organization laid off all the technical writers. The market in Utah (where I was living) wasn't so hot, so I decided to move to the mecca of tech: Silicon Valley, California.

Silicon Valley, it turns out, has a lot of jobs for API technical writers. I'd been wanting to define a trajectory for my career that didn't lead to management, and since I felt confident in my technical abilities, I decided to take a job doing API documentation at a startup company specializing in gamification.

I soon realized why I'd been hired. The existing writer felt overwhelmed by a REST API and JavaScript SDK that she had to document. The company had been looking for a writer with strong development skills who could both write fluently as well as understand the depths of JavaScript code.

I studied up on JavaScript programming as best I could and managed to muddle my way through the writing tasks. As I worked on the documentation, particularly for the JavaScript SDK, I realized that I was entering a territory that was unfamiliar to me. My previous 8 years of technical writing experience, including the numerous conferences I'd attended, really didn't prepare me for all the questions I had.

I had questions like, what tools should I use to document this API and SDK? How do I understand all of this programming code? How do I know if this API documentation contains useful information for developers? Will my audience know what this code does by merely looking at it, or do I need to explain it in detail? Do I put my documentation in the source code or another place?

I realized that API documentation, or rather developer documentation, is a sub-specialization in the tech comm profession — a specialization that doesn't have many resources or information to guide technical writers like me. In fact, about the only book on API documentation is an out-of-print book written nearly 8 years ago (which dives into Java instead of REST APIs, which are now more common).

The most relevant conference for those doing API documentation, WriteTheDocs.org, is so removed from regular tech comm events that the participants (many of whom are developers) refer to technical writers as "documentarians."

APIs are proliferating on the web more than ever before. Programmableweb.com, a site that tracks and covers web APIs, has a directory of more than 11,000 web APIs. If you look at the documentation for these APIs, almost none of them are the same in terms of format and style. Their approaches differ as much as any wild west frontier you can imagine.

There is a great need for technical writers who can speak code fluently enough to document all the APIs coming out of Silicon Valley and elsewhere. While Java has traditionally used Javadocs for source-generated documentation, and C++ has used Doxygen, and .NET has used Sandcastle, REST APIs are a breed of their own, with no tool facilitating source-generated documentation. They present a lot of opportunity not only for communication expertise, but also creativity in layout, display, and organization.

This issue of Intercom is full of articles about API documentation. Beyond the print versions included here, you'll also find additional articles about API documentation in the online version of the Intercom site. I hope these articles help increase much-needed instruction about API documentation in our field.

If you've been thinking about taking your career in a new direction, consider specializing in API documentation. Not only will it challenge and expand your technical abilities, it will also give you a new landscape to play in, job security, higher salary potential, and a host of challenges to solve.

About the Author

Tom Johnson ([email protected]) is a senior technical writer for 41st Parameter, a company specializing in fraud detection and device identity recognition. He writes about API documentation and other technical writing topics on his blog, idratherbewriting.com. He lives in San Jose, California and is a member of the Silicon Valley STC chapter.