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.
Sandy's link to "literate programming" stuff is good background reading.
If the code you are documenting is written in C++ then you can get
some excellent results using Perceps: http://starship.python.net/crew/tbryan/PERCEPS/
Which is free software. It produces good documentation of all the
classes and functions etc., as hierarchical html pages. If you wish,
you can add source code comments in a set format and they will
be extracted and placed in the right points in the html pages. It works
for us. Can't comment in Doxygen as not used it.
I wouldn't write your own scripts to strip comments unless you
are looking for a project to do -- such tools have been written before,
and are available for free.
I'm pretty certain we had a discussion on this topic last year,
not sure what the thread name would have been though
as I think we digressed from another subject... one comment
I made at that time though was to be sure that the techwriter
and developer teams know who can edit what --- and that,
unless your source code is the cleanest in the world, you
might want to check some of the comments that developers
write before showing them to customers... I once found the
following comments in live source code (not at my present
employer I hasten to add!) :-)
% This used to be wrong but didn't work so now I've fixed
% it and it's right, but it doesn't work...
and
% This code has more bugs than a tramps overcoat...
Christopher Gooch, Technical Author
LightWork Design, Sheffield, UK.
chris -dot- gooch -at- lightworkdesign -dot- com www.lightworkdesign.com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Free copy of ARTS PDF Tools when you register for the PDF
Conference by April 30. Leading-Edge Practices for Enterprise
& Government, June 3-5, Bethesda,MD. www.PDFConference.com
Are you using Doc-to-Help or ForeHelp? Switch to RoboHelp for Word for $249
or to RoboHelp Office for only $499. Get the PC Magazine five-star rated
Help authoring tool for less! Go to http://www.ehelp.com/techwr
---
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.
