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.
Geoff Hart wrote:
>
> Michael Collier reports <<... 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. >>
>
> Never worked with such a system, but it seems to me to be a
> classic example
> of the garbage in, garbage out rule: if the developers insert
> well-written,
> consistent, helpful comments, you'll get something you can at
> least build
> on. Anyone want to bet on whether that's reliably going to be
> the case? If
> nothing else, I imagine that such tools would be a great way
> for building
> functional specifications on the fly, and if you work for a
> company where
> such docs are never created, it might be worth your while to
> invest in one,
> purely in self defence.
---
In Feb 1999, I needed to document an API and sought a commercial tool for
this. Although I received some recommendations, the suggested applications
were not up to the task. Here's an extract from my summary of 12 Feb 1999:
---
Thanks to Geoff Hart, who suggested that the developer was the best tool for
the job<g>. To some extent, I've implemented his suggestion<bg>.
Hopefully these will suit your needs better than mine<g>. For my solution, I
wrote a (project-specific) Word application that scanned the source files to
extract specific comments. This still produces the in-house API
documentation and (thanks to a development manager who understands the need
for good docs) requires little rework for an external audience.
HTH,
Geoff Lane
Cornwall, UK
geoff -at- gjctech -dot- co -dot- uk
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
