Newsletter of the Society for Technical Communication, San Francisco Chapter
February/March 2007
| Newsletter of the Society for Technical Communication, San Francisco Chapter February/March 2007 |
James Bisso, CTO of Bitzone LLC (www.bitzone.com), provided valuable insight into the world of API documentation at the November San Francisco STC meeting.
Bisso said that many technical writers new to developer documentation feel lost when asked to document an API (application programmer interface) even if they have years of proven technical writing experience. He pointed out that many of the skills seasoned technical writers possess can be used when documenting APIs. Much like a user documentation writer, an API doc writer:
Although many tried and true technical writing skills are transferable from writing user documentation, documenting APIs and creating other reference materials for a developer audience presents unique challenges.
A developer documentation writer generally needs to know how to read code to be successful. That's not to say that an API writer must be a programmer, but having the ability to interpret code is essential to writing about it, Bisso said.
"You have to be able to say, 'That's a class, that's a method,'" Bisso said. "You should take a programming class to at least get a taste of the programming language."
He also recommended studying programming design patterns. "APIs have usage patterns that are in the developer's mind," he said. "Once you know the patterns, you will start to see them used over and over again."
He recommended reading Design Patterns: Elements of Reusable Object-Oriented Software (Addison Wesley) or Head First Design Patterns (O'Reilly Media).
Developing this foundational knowledge will also help you communicate more effectively with programmers and gain their respect.
Other aspects of API writing that are different from traditional user documentation writing are the deliverables. In general, an API writer produces:
The style of writing is also different. Whereas a typical user documentation writer is expected to include a lot of detail, background information, and task-oriented subjects, for the reference guide the API docs writer is expected to write succinct, direct explanations of the elements of programming code.
For your first week on the job as an API docs writer, Bisso recommends that you gather all the existing API and SDK (software developer kit) documentation, functional specifications, manuals, competitor documentation and third-party documentation (if available). Talk to SMEs (system architects or others knowledgeable about the API, such as product managers) and interview them for the high-level overview.
If you would like to learn more about becoming an API documentation writer, Bisso and his business partner, Victoria Maki, have written a text book entitled Documenting APIs: Writing Developer Documentation for Java APIs and SDKs, which is available at www.bitzone.com. Bitzone also offers an online training course on the subject.
Brenda Jordan is a member of the San Francisco STC chapter and is currently working as a senior technical writer at Ultratech in San Jose. She has a background in daily newspaper reporting and graduated from Kent State University. She enjoys living and working as a technical writer in the San Francisco area.