RE: Quote of the Day

["Combs, Richard" <richard -dot- combs -at- Polycom -dot- com>]

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
gov.nist.javax.sdp.fields.ConnectionField:

 	getNetworkType()
          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.
Oops. 

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
http://www-x.antd.nist.gov/proj/iptel/.)

Richard


------
Richard G. Combs
Senior Technical Writer
Polycom, Inc.
richardDOTcombs AT polycomDOTcom
303-223-5111
------
rgcombs AT gmailDOTcom
303-777-0436
------




^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.
http://www.DocToHelp.com/TechwrlList

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

---
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 http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


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
http://www.techwr-l.com/ for more resources and info.