RE: Quote of the Day

Subject: RE: Quote of the Day
From: "Combs, Richard" <richard -dot- combs -at- Polycom -dot- com>
To: "Jim Barrow" <vrfour -at- verizon -dot- net>, <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Thu, 30 Aug 2007 09:54:54 -0600

Jim Barrow wrote:

> That's one possibility. In my case the developers mistakenly
> believe that they would be able to produce required
> documentation from the JavaDoc tool. I don't mean that they
> think they can generate their comments, I mean they think
> they would be able to generate fully-formatted,
> ready-for-publication documents, replete with graphics, TOC,
> headers and footers.

They probably can. Maybe not the graphics. And maybe with
"ready-for-publication" interpreted a bit loosely. But creating a PDF
from Javadoc isn't rocket science. They can probably create a
serviceable PDF, complete with headers, footers, and TOC, that includes
all the classes, methods, and fields, shows the class hierarchy, etc.

The problem is that the only explanations of anything will be their
sucky comments. Complete with misspellings, useless descriptions,
cloning errors, ...

Here's an example from the National Institute of Standards and
Technology's Javadoc pages for JAIN-SIP, an API for IP telephony
signaling -- a few method descriptions for

Returns the type of the network for this Connection.
setAddress(ConnectionAddress a)
Set the address member
setAddress(java.lang.String addr)
Sets the type of the address for this Connection.
setAddressType(java.lang.String type)
Returns the type of the network for this Connection.
setAddrType(java.lang.String a)
Set the addrtype member
setNettype(java.lang.String n)
Set the nettype member
setNetworkType(java.lang.String type)
Sets the type of the network for this Connection.

Notice how most of the descriptions merely restate the method name (IME,
that's all that 90% of the descriptions in Javadocs do). The exception
is setAddressType, which has the same description as getNetworkType.

This is why software developers are so fond of code examples and
O'Reilly "Nutshell" books -- the reference documentation available to
them generally sucks.

(FYI, the NIST IP telephony project is at


Richard G. Combs
Senior Technical Writer
Polycom, Inc.
richardDOTcombs AT polycomDOTcom
rgcombs AT gmailDOTcom


Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more.

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity!

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Re: Quote of the Day: From: Jim Barrow

Previous by Author: RE: Quote of the Day
Next by Author: RE: Popularity of FrameMaker and Web Works Publisher; Suitability of Adobe Robohelp
Previous by Thread: Re: Quote of the Day
Next by Thread: HELP, my g-mail address has been "hijacked"!!

What this post helpful? Share it with friends and colleagues:

Sponsored Ads