Adobe Robohelp

Get new posts delivered straight to your inbox.

Subscriber count: 3,220

Adobe Robohelp

STC Intercom Issue Entirely Dedicated to API Documentation

Sep 10, 2014 • api-doc, general

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.
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.)


What Is API Documentation?

By Scot Marvin

This article describes what an API is, what API documentation contains, the audience for this type of documentation, and how you can get started in this field.


How Do You Break into API Documentation?

By Mary Connor

An overview of the market for API documentation, including a description of the salaries, the working environment, the expected skillsets, and how to transition and train for an API career.


What Factors Contribute to Good API Documentation?

By Lois Patterson

The author outlines some considerations for evaluating whether your API documentation efforts result in good documentation that is usable and helpful to the audience.


Lessons Learned as a Novice API Writer

By Mary Linderman

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.


How to Write Helpful Code Samples

By Sarah Maddox

How can technical communicators write code samples? This article describes the nature and purpose of code samples, and gives guidelines on how to write them.


How Much Programming Do You Need to Know to Write API Documentation?

By Samuel Wright

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.


What Tools Do You Use to Produce API Documentation?

By Anita Andrew

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.


REST API for Dummies. What Does the Developer Expect From Your REST API Documentation?

By Dmitriy Mironov

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.


How Does API Documentation Differ from GUI Documentation?

By Cyrus R. Kirby

There are two sides to technology that a content developer supports. The side that most people are familiar with is an application's interface.


API Writing: More than Making API Docs Pretty

By Cherie Woo

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

Tom Johnson, 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 (tom@idratherbewriting.com) 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.

You can view the STC September 2014 Intercom issue here.


Get new posts delivered straight to your inbox.

Subscriber count: 3,220

About Tom Johnson

Tom Johnson

I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include technical writing, authoring and publishing tools, API documentation, tech comm trends, visual communication, technical writing career advice, information architecture and findability, developer documentation, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here.