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.
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.)
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 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.
I'd Rather Be Writing Newsletter
Get new posts delivered straight to your inbox.
About Tom Johnson
I'm a technical writer based in the California San Francisco Bay area. In this blog, I write about topics related to technical communication — Swagger, agile, trends, learning, plain language, quick reference guides, tech comm careers, academics, and more. I'm interested in simplifying complexity, API documentation, visual communication, information architecture and findability, and more. If you're a technical writer of any kind (progressional, transitioning, student), be sure to subscribe to email updates using the form above. You can learn more about me here. You can also contact me with questions.