Source code documentation systems?

Subject: Source code documentation systems?
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 24 Jan 2001 08:20:04 -0500

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.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html

"Technical writing... requires understanding the audience, understanding
what activities the user wants to accomplish, and translating the often
idiosyncratic and unplanned design into something that appears to make
sense."--Donald Norman, The Invisible Computer

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


Previous by Author: What to call them?
Next by Author: Quality assurance procedures for technical writing?
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