Re: Source Code Documentation Systems?

Subject: Re: Source Code Documentation Systems?
From: Meg H <aiki4us -at- yahoo -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 24 Jan 2001 07:32:10 -0800 (PST)

Michael Collier asks about...

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?ve never worked with one of these systems, but have
my doubts about their ability to generate useful help.
I do a lot of reverse engineering of legacy Fortran
code. Often the authors are long gone and we are
attempting to figure out exactly what the code does
and the principles behind the code.

The ability of such a system to create documentation
would depend greatly on the care of the analysts in
(1) commenting the code and (2) writing clear code.
Too often, the comments are obscure, unreleasable
(amazing some of the stuff that turns up!), or simply
absent. Equally often the code -- especially old code
-- is labyrinthine. Or the code is just put together
strangely. One guy named all his variables after old
girlfriends. I would have hated to figure that one
out. Further, such a utility won?t be able to do the
essential task of tuning the documentation to a the

However, these utilities can help YOU document the
code by consolidating and organizing what information
there is in the code.

-- Meg

Do You Yahoo!?
Yahoo! Auctions - Buy the things you want at great prices.

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: Acrobat Bible? ( was Best remote tools for tech. writing)
Next by Author: Word 97 landscape upside down from HP printers
Previous by Thread: RE: Source code documentation systems?
Next by Thread: RE: Source Code Documentation Systems?

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

Sponsored Ads