by Susan W. Gallagher

Information about API documentation is difficult to come by, and a DVD training course is a welcome and significant addition to this meager library. As the marketing literature suggests, individuals can use the video training as a self-paced lecture series, following along in their workbooks as the seminar unfolds on the TV or computer screen. Documenting APIs and SDKs can provide a cost-effective means of bringing a department up to speed or for training new employees as needed. To the manager of an API doc team, it sounds like a dream come true!

So, how well did Gordon & Gordon do in making this dream a reality? Did they hit the mark? Is this product worth the
price of admission? [1]

What You See

Documenting APIs and SDKs sits you in a meeting room in an anonymous hotel to attend a three-hour workshop presented by Manual Gordon. The kit provides you with a workbook, primarily a set of slides, in which to follow along and to take notes. Manny Gordon is an accomplished speaker who does an excellent job of presenting the course.

The course itself is a good overview of API and SDK documentation. Manny explains in great detail what APIs and SDKs are and how they are used, who the target audience is, and what the typical documentation set comprises. Without delving into the complexities of programming languages, Manny does a great job of explaining what all the different pieces in the documentation set look like, how the uninitiated technical writer can create these deliverables, and even where to cut corners when you're short on time.

The information presented in the workshop is both valid and valuable, but it could have been better. Manny has a lot of great things to say about the kinds of examples to include in API documentation and which examples to put where. But when the lecture came around to the explanation of examples, most of the really good stuff was left on the cutting room floor and the words "Manny is now talking about xxx examples and not yyy examples" appear at the bottom of the screen several times. The resulting jumps in continuity had me hitting the Back button while I tried to put the pieces together. The disorientation lasted for a good while as Manny referred back to things you never heard him say. Certainly, the presentation would be richer had this information been left in.

Along with the excellent information on documenting APIs and the solid advice on general writing technique, you also get an ounce or two of Manny's view of the world. According to Manny, all UNIX programmers are tall and skinny; structured code was much nicer to document than OO code is, and youíre going to have to lower your standards when you enter the world of API documentation. I don't necessarily agree with any of these views, myself. (I have met short and portly, and even female UNIX programmers.)

If Manny gives any bad advice at all, itís when he advises the listener to take a supplicantís role when documenting APIs ≠ to assure the developers that it is their API and their manual, and the lowly technical writer ought defer to their better judgment. In my experience, technical writers who learn the products and processes that they're documenting and who bring their talents to the table as equal partners, produce the best documentation and form the best team relationships. But thatís my soapbox and, for
many, Manny's approach works sufficiently well.

What You Get

The training kit consists of two DVDs approximating three hours of playing time, a Getting Started booklet, and a spiral-bound workbook. The workbook contains 96 slides for the workshop, the excellent paper What Programmers Really Want (which is also available on the Gordon & Gordon [2] website) a ten-page glossary of programming terms, and several pages of miscellaneous technical writing and marketing communication references.

The quality of the DVD production is excellent and the top-level menu structure provides convenient access to individual modules and a Play All option. The camera work is acceptable, but the sound keeps fading in and out, making Manny sound like heís trapped in the bottom of a well for almost five full minutes at the beginning of the second disc and frequently for shorter intervals throughout the presentation.

The printed material must be an example of the lower standards that Manny says we must learn to expect when we transition to API documentation. While the high-tech notebook/box is impressive (although mine arrived with a crack in the binding), the presentation is lackluster in general. The booklet software used to generate the Getting Started booklet apparently malfunctioned; a list that begins on page 2 continues on page 5. And the glossary changes from sans serif to serif in mid-stream for no apparent reason.

The information contained in the glossary is a little shallow and somewhat Windows-centric, but not a bad place to start. Just don't take it all as gospel. And I'm not entirely sure why they decided to include marketing communication references in an API course. For the intended audience, the information adds only to the total page count.

Who Should Buy This

This workshop contains valuable information for anyone who has never written API documentation and wants to get started. But beginners should be aware that, while the workshop does not discuss specific programming languages, it does use programming terminology; the viewer would be wise to do a little terminology homework before clicking Play.

The presentation would definitely benefit from a group setting, and there are places in the presentation to pause for discussion. Additional workbooks are available at the Gordon & Gordon website. If you have a group of writers to train in API documentation, the kit is certainly the cost-effective approach.

The attention to good writing principles makes the workshop a good candidate for training programmers to write API documentation. It may indeed be "just enough writing" to get a programming team up to speed to produce its own API docs. This same attention to writing principles, however, may make the workshop a little slow paced for more experienced writers.

It says on the website and in the Getting Started Guide that writers who have been through the process of creating API documentation can also use the workshop to verify their approach, and perhaps there are some writers who would benefit from that. But for the most part, the information is targeted toward those who have never done the job and most writers who have fumbled
through a first API documentation delivery will have far more specific and targeted questions than this workshop answers.

Technology [2]

• API [2]

Writing and Editing [2]

• Writing General [2]
• Reviews [2]