ISSUE 5: OCTOBER 2006

In This Issue:

• The Face of E-Learning is Changing
• Documenting APIs: Book Review
• The Oak Hill Queen's Guide to Success

CURRENT ISSUE

• July 2008

FROM THE ARCHIVES

• January 2008
• August 2007
• April 2007
• October 2006
• July 2006
• April 2006
• December 2005
• September 2005

JOIN US

Subscribe
Tell a Friend

DOCUMENTING APIs: BOOK REVIEW

Documenting APIs: Writing Developer Documentation for Java™ APIs and SDKs is the first book to describe how to document API and SDKs. Written in an easy-to-follow, user-friendly style, it is designed to be a "course in a book" for technical writers new to documenting Java APIs and programmers new to writing API documentation.

In addition to answering common questions, such as "what is an API?", the book provides the background information necessary for a deeper understanding of API documentation.

For example, here is an excerpt from Chapter 2, "An Introduction to Developer Documentation":

"Developer documentation primarily describes three aspects of an API:

• The structure of the API–The classes, methods, and other constituent
  parts that make up the architecture of the software being created.
• The functionality that the API provides–The capabilities that the API
  makes available for third-party development.
• The way in which individual software components can be used to form
  larger functional units–The constituent parts in a complex API are
  often logically grouped into functional units, such as packages."

Practical tips, such as questions to ask in an initial interview with a subject matter expert, help the reader understand how to approach documenting an API. One chapter takes the reader step-by-step through the process of writing an API reference guide and programmer's guide.

Technical writers new to documenting APIs often despair at the lack of resources, including actual code projects to document. Documenting APIs includes four sample code projects available for download from the Bitzone web site. One of these, the TAFT Project, is a complete plug-in application. Part 4 of the book is a sample documentation set for the TAFT Project, including a functional specification, a reference guide, and a programmer's guide.

Tutorial code is often included with a programmer's guide to illustrate the development process. The TAFT Plug-in Project is a sample application that is included with TAFT as tutorial code. It illustrates to the developer how to develop and install a TAFT plug-in as well as how to write the accompanying XML configuration file.

With its sample code projects and an accompanying study guide, Documenting APIs: Writing Developer Documentation for Java™ APIs and SDKs serves as a valuable and necessary resource for writers and others concerned with documenting an API.

Documenting APIs: Writing Developer Documentation for Java™ APIs and SDKs
by James F. Bisso and Victoria Maki
List price: $49.95
318 pages, including four sample code projects and a study guide
ISBN: 0-9630021-0-4
Second printing published July 2006 by Bitzone and available only from the
Bitzone web site, www.bitzone.com.