Documenting APIs: Your First Week on the Job

by Kathryn Munn
Berkeley STC Chapter

(Editor's note: This article appeared in slightly different form in the October 2006 issue of Ragged Left, the newsletter of the Berkeley STC chapter. It is based on a program presented by Jim Bisso at the September 2006 Berkeley STC chapter meeting, and repeated at the January 2007 EBSTC chapter meeting.)

This presentation evolved in part from frequent questions to presenter Jim Bisso and Viki Maki, principals at Bitzone LLC, from technical writers assigned the job of documenting an Application Programming Interface (API) for the first time. Jim and Viki, co-writers of the book Documenting APIs: Writing Developer Documentation for Java APIs and SDKs and co-leaders of the Silicon Valley STC chapter Technical/API Docs SIG are providing innovative professional resources and information in this specialized area of technical communication. Visit Bitzone's web site (www.bitzone.com) for additional information and training opportunities. In his presentation Jim reviewed and contrasted the processes and skills used in creating task-based user documentation and developer reference documentation, also called APIs. The familiar processes of learning to use the software user interface (UI) and defining user tasks are not used in defining the reference information needed by developers. Similarly the cycle of defining deliverables, gathering source documents, planning, preparing alpha drafts, revising, reviewing, releasing, and maintaining documentation differs with the creation of API documents. In the case of an API, the audience is most often a third-party developer who will be accessing the functionality of the API through documentation, typically including code samples.

Knowledge of the programming language of the API and object-oriented concepts are necessary skills of the API technical writer. Writers should be able to recognize class declarations or method signatures, format and document code samples, and write tutorials or sample applications. Jim also emphasized that the API writer should have good problem solving skills, heuristics, as described in the 1945 book by Polya, How to Solve It. The API writer should ideally bring domain knowledge to the job such as knowledge of technology standards and protocols relevant to the API, industry knowledge such as accounting or business processes, and framework or software architecture design.

Documentation deliverables for an API will typically include a reference guide, structured along the near standard of the Javadoc tool, and may include a programmer's guide with a description of how and why to use the API using more fully developed demo or sample code. Documentation plans related to these documents will be concerned with planning complete coverage of the packages (or namespaces), existing classes and their constituent members, milestones coordinated with the product, and defining the print or web based deliverables.

To begin gathering resources to document an API, the writer will get to know the product by reviewing earlier versions if available, documentation such as functional specifications, and competitor products. If specifications are not available, the writer should create a high level overview by interviewing the architect, product manager, or senior level programmer. As with all documentation the subject matter experts are identified and may include the software architect, product managers, programmers, and support and quality assurance engineers. Finally, the technical writer will bring their own domain knowledge to the project. Jim's well-received presentation closed with audience questions.