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 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 think it depends on what sort of code you are documenting
and the aim of the documentation.
What such systems can give you amounts to documenting the
code --- useful for documenting an API, not so useful for
producing an end-user guide for an accounts package. However
if used properly it could provide very useful internal
documentation of the code which will make future code
maintenance much simpler (I shall avoid kicking off another
discussion about whether producing such a document is a
job for a TW or a software engineer!).
It is also of course vital to bear in mind that the
software engineers / programmers will have to adopt
rigorous coding conventions to get much out of it, and
to accept that fact that, if you want to use such stuff
for end-user documentation, even of an API, you may well
have to spend time editing before you "publish", unless
you are confident of the writing style of the engineers
(Bruce is right to point out that some of the things
you sometimes see written in source code *really*
shouldn't be for public/customer consumption!!).
This would then present the issue of whether you edit
text directly in the source code, or in the finalised
docs built from that source code -- in which case you
will have to do it again each rev.
If you do intend to publish documentation derived in such
a way to 3rd parties, I think it is worth bearing in mind
that you are, effectively, publishing aspects of your
source code, and you need to be clear if this is what
you intend or not. For example, there may be parts of
your code that you do not wish to draw customer attention
to (maybe it's not quite the finished article) whilst
at the same time documenting clearly for internal use.
If there is any difference between how you want to
document your code internally and how you want to
document it for external consumption, then you will
encounter issues :-)
Having said that, taking this approach can be very
useful for documenting APIs, particularly if the system
is object oriented (C++, Java) rather than flat (C).
This is because if the system is well designed it
should make a reasonable job of clearly presenting the
structure/hierarchy.
For those who are interested in such matters, taken
to its logical conclusion such an approach to
software development (and this is how you should
think of it, rather than the more common "docs
as an afterthought") is called Literate Programming.
Don Knuth, he of the Art of Computer Programming
wrote the TeX typesetting system partly to allow
Literate Programming.
Less arcanely, I can tell you that we have made
use of the Perforce system at my current employer
and sister company, which as well as being a
quite decent source / revision control system,
also produces fairly neat html documentation
of C++ functions and classes, driven I believe
by Perl scripts (which you can therefore
customize), and only requires fairly sensible
commenting conventions of the programmers.
Of course, it's correct to observe that you
could enforce some commenting conventions and
then write some perl (or similar) scripts yourself,
but you may find that to be quite a time
consuming project :-) (or you may not be an
expert in such things).
HTH
Christopher Gooch, Technical Author,
LightWork Design Ltd., Sheffield, England.
chris -at- lightwork -dot- co -dot- uk www.lightwork.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.
