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.
I wouldn't want to work on any SDK or code documentation project without
tools! It is a waste of time, because our documentation can slip quickly and
COMPLETELY out of synch with the code we're documenting if no tools are
used.
At my new employer, an engineer found a SHAREWARE tool called Doxygen
(www.doxygen.org) for C/C++ that I am really impressed with. All of those
hard-to-maintain homegrown Perl scripts at a previous employer pale in
comparision to what Doxygen can do.
One of its benefits is that reference information is located where it
belongs: in the source code. It is not separated from the code in a
FrameMaker book that we must constantly maintain through every whim of the
engineer's ordering, adding, and deleting of arguments. Those things are
taken directly from the declarations and definitions. If you change the
formatting of code comments slightly, they will be extracted and included in
your documentation system (HTML, RTF/HLP, or LATEX). It's automatic, and
code references (e.g., function arguments) in the published documentation
are never out of synch with the code, providing that Doxygen is run against
the code at code freeze or other applicable points in time.
As an aside, developers are amazed at the Doxygen output even if no code
comments have been modified to be Doxygen comments. You really do get an
overview of the code, what is derived from what, automatic hyperlinking,
marked-up copies of the source files, etc.
Because the reference information is in the source code, it has another
benefit (or drawback) in that developers more actively maintain it. This
frees me up from describing function arguments (and other low-level,
implementation details) to describing the big picture of how the functions
work together or should be used by the engineers working with our SDK. This
latter information I'll produce in FrameMaker and single-source into PDF and
a mini-HTML system, both of which I'll link into the Doxygen code reference
HTML mini-system.
The early postings (below) about "garbage-in, garbage-out" do hold true to
some extent. But let's not throw the baby out with the bath water. A wealth
of reliable information can be obtained from Doxygen even if no (garbage)
comments are extracted. Because we now have the tools to expose those
comments quickly and conveniently to the end-user or other peer engineers
here (i.e., for code reviews), the owning engineers have more incentive to
write better comments. And I stand at their disposal to review any comments
in source files that they trust me with write-access to.
We're in the process of implementing Doxygen into our normal engineering
processes here. We have established a working group to update our coding
conventions, and the use of Doxygen will be one of the new additions. The
coding guidelines are aimed at providing consistency in our software
development, increasing our code reliability, improving the maintainability,
and re-enforcing good coding practices.
Doxygen is going to end up playing a major role in bringing new employees up
to speed, in enforcing coding practices, in providing a basis for code
review, and in significantly easing the burden of the documentation group,
not to mention the comprehensive HTML system that source-code customers will
get.
Doxygen is shareware. It does have one drawback. I ran Doxygen on the
Doxygen code. Evidently, the developer did not practice what he preached;
the code is not commented. This makes it more difficult to make minor tweaks
or major changes (such as adding support for new types of code items).
Glenn Maxey
Voyant Technologies, Inc.
Tel. +1 303.223.5164
Fax. +1 303.223.5275
glenn -dot- maxey -at- voyanttech -dot- com
> -----Original Message-----
> From: bounce-techwr-l-58477 -at- lists -dot- raycomm -dot- com
> [mailto:bounce-techwr-l-58477 -at- lists -dot- raycomm -dot- com]On Behalf Of Hart, Geoff
> Sent: Wednesday, January 24, 2001 6:20 AM
> To: TECHWR-L
> Subject: Source code documentation systems?
>
>
> 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. >>
> Geoff Hart reports <<
> 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.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
