Book Review: Documenting APIs—
Writing Developer Documentation for Java APIs and SDKs

by Richard Mateosian

(Editor's note: This review appeared in slightly different form in the Sept/Oct 2006 issue of IEEE Micro, Copyright C 2006, IEEE.)

Documenting APIs—Writing Developer Documentation for
Java APIs and SDKs

James F. Bisso and Victoria Maki
Bitzone, Richmond CA, 2006, 318pp, ISBN 0-9630021-0-4,
www.bitzone.com , $49.95

I have known and worked with the authors of this book for many years. Jim Bisso is a software engineer at Sun Microsystems. Viki Maki is a technical writer and trainer. Both have taught classes in technical documentation.

The authors take you through all aspects of documenting Java APIs (application programming interfaces). They explain the different roles of different kinds of API documentation. For example, a programmer's guide and an API reference serve different purposes and complement each other.

Though the authors focus on Java, much in the book applies to API programming for other languages. Buying the book entitles you to access additional information from an associated website containing sample projects to which the book refers.

The authors write from the viewpoint of the person documenting the interfaces, but developers can get valuable insights from understanding that viewpoint. In many cases, developers provide the bulk of API documentation.

My connection with the authors makes me a biased reviewer, so I am hesitant to say too much about the book. I think I am safe, however, in saying that this is the only book on this subject. If you are involved in API documentation, you should definitely read it.