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.)
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
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.
You can view the STC September 2014 Intercom issue here.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.