TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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
audience.
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. http://auctions.yahoo.com/
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Develop HTML-Based Help with Macromedia Dreamweaver 4 ($100 STC Discount)
**WEST COAST LOCATIONS** San Jose (Mar 1-2), San Francisco (Apr 16-17) http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.
Sponsored by DigiPub Solutions Corp, producers of PDF 2001
Conference East, June 4-5, Baltimore/Washington D.C. area. http://www.pdfconference.com 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 http://www.raycomm.com/techwhirl/ for more resources and info.
