Re: Source Code Documentation Systems?

Subject: Re: Source Code Documentation Systems?
From: Bruce Byfield <bbyfield -at- progeny -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 23 Jan 2001 15:19:58 -0800

Michael Collier wrote:
> I come across ads here and there for these systems, marketed to
> developers, which typically claim to find objects and comments in source
> code (Java, C, C++), create some kind of documentation based on these
> and output to RTF, HTML, HTML help.
> Has anyone ever worked with systems like these, or had to write actual
> user material from the output they generate? I'm wondering how useful
> these systems might be for creating user documents. Especially if they
> are outputting to help, it would seem that's what they are trying to do.

I'm skeptical, especially if you have to pay. You can easily do a
search, with output written to file, then open the file in a word
processor and save in the format you desire. The programs might save
you a little time, but not enough to be worth more than $30 or $40.

In general, how useful such programs are depends to a large extent
on how the programmers you are working with comment code. Some
coders rarely comment, while a generous minority give extremely
detailed information, including examples.

At any rate, you would want to go over the results very carefully. I
would expect the programs to have only limited judgement about what
was useful. Moreover, comments aren't always written in language
that you'd want to pass on to your customers. Swearing, jokes, and
even private company information can sometimes be dropped into
comments. Nor would the result be very useful for task-oriented
writing without substantial restructuring.

I've heard of writers whose idea of their job is to cut and paste
comments from the code, but the ones I've met who work this way are
mediocre writers producing even worse documentation. Code comments
can be a useful source of information, but, in my experience, they
need to be heavily massaged before they're in usable form.

Bruce Byfield 604.421.7177 bbyfield -at- progeny -dot- com
Director of Marketing and Communications, Progeny Linux Systems
Contributing Editor, Maximum Linux

"'Do you know medicine? Chemistry? A little biology perhaps?'

"'My education was a little too expensive for that, I'm afraid.'"

- John Le Carre, "The Constant Gardener"

Develop HTML-Based Help with Macromedia Dreamweaver 4 ($100 STC Discount)
**WEST COAST LOCATIONS** San Jose (Mar 1-2), San Francisco (Apr 16-17) or 800-646-9989.

Sponsored by DigiPub Solutions Corp, producers of PDF 2001
Conference East, June 4-5, Baltimore/Washington D.C. area. or toll-free 877/278-2131.

You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.

Previous by Author: Re: Technical Writers who write functional specifications
Next by Author: Re: Typical Book Deal?
Previous by Thread: Source Code Documentation Systems?
Next by Thread: Re: Source Code Documentation Systems?

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

Sponsored Ads