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.
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) 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.
