Newsletter of the Society for Technical Communication, San Francisco Chapter
June/July 2005
| Newsletter of the Society for Technical Communication, San Francisco Chapter June/July 2005 |
At the March meeting, James Bisso, President of Bitzone LLC (www.bitzone.com), discussed how technical communicators can use tutorials, sample applications, and code snippets to create programmer’s reference guides for application program(ming) interfaces (APIs).
APIs are the interface between two components or entities. They allow third-party developers to extend the functionality of software. For example, the API for FrameMaker allows Frank Sterns Associates to develop and market IXgen, which is a series of macros for managing index markers in FrameMaker. These macros are a tremendous improvement over the primitive indexing tools built into FrameMaker.
During this talk, Bisso focused on two primary types of developer documentation: reference guides and programmer’s guides.
To write a programmer’s guide, technical communicators must have a deeper understanding of customer requirements than that required for API documentation. Bisso pointed out the following sources for obtaining this knowledge:
Other resources include training, product marketing, and consultants.
To become proficient in creating programmer’s guides, technical communicators need to go beyond just knowing a programming language. They need to understand the idioms of programming languages, the design patterns solving common problems, and the structures for using APIs to solve real-life problems.
As with natural languages, each programming language has its own idioms, which are its own characteristic means of expression. When people learn English as a second language, no matter how proficiently, the idioms of their native language often remain recognizable. The same is true in programming languages. For example, C++ has its own characteristic keywords, types, and constructs. When C++ programmers write Java code, they do so with a C++ accent.
Design patterns is a concept from architecture that has found its way into programming. A design pattern is a way to define a recurring problem and a solution that can be reused in different situations with a minimum of changes. In architecture, a well-designed building has its own particular adaptation of common solutions to architectural problems. In programming, applying a design pattern involves taking a “solution [that] is a general arrangement of objects and classes that solve the problem,” then customizing the solution for a particular context (Gang of Four, Design Patterns).
Structure means breaking up a task into chunks for implementation. A programmer’s guide should go beyond the “what” (code samples and readme files) and move on to the “how” and the “why” (code samples with tutorials). For example, customers need to complete 10 steps to implement an API. The programmer’s guide should include sample code and an explanation of each step –- both individually and how it fits in with the other steps.
Different people have different learning styles. A programmer’s guide can accommodate these differences with the following:
So you want to create developer documents? Bisso suggested the following steps for getting started:
Bisso is the author of a book entitled Documenting APIs: Writing Developer Documentation for Java™ APIs and SDKs. Also, Bitzone offers classes in writing API documentation. For more information about the book or the classes, email Viki Maki at vmaki@bitzone.com.
Marc Smircich is a technical writer with over 15 years experience in documenting financial and human resources applications.
Copyright © 2005 by the Society for Technical Communication, San Francisco Chapter (www.stc-sf.org). This article may be reprinted in another STC publication under the provisions of the chapter's copyright policy.