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.
Sorry about my delay in writing. I had in-house product training on Saturday
so took Monday as a comp day.
There are several tools out there for extracting prototypes (and code
comments). I personally haven't researched this. Our development staff
already stumbled upon the free tools that we're using (www.doxygen.org and
Javadoc). It turns out that our new design tools might have some of this
capability built-in.
If I were to give you any pointers, it would be to approach some of your
lead developers. Ask them what tools they know about for extracting
prototypes and comments from code, what would their preference be, etc. Get
them involved. Have them at least download, install, compile, and run one or
two of the free tools, like Doxygen. See if they like the output.
By turning the tables a little bit and by getting development involved,
you'll make a lot more headway. In fact, they'll become your tech support,
part-time content providers, and chief advocates for the solution you do go
with.
As far as your outline is concerned, that is going to be unique to your
organization. The tools approach that I've been advocating isn't going to
help you much except in one area that I'll illustrate by way of a story.
At a previous employer where we documented API's, we weren't using
off-the-shelf tools; we did everything in-house. Part of the reason for this
was that there weren't any affordable ones on the market when they embarked
on that path. (Part of the reason was that our tech pubs programmer was very
stubborn, had the "wasn't programmed here [by him]" attitude for anything
coming from external sources [let alone tweaks from me], and probably never
even researched the matter ever, as became clear in other unrelated faulty
design decisions that he made in a vacume.) He was rightfully proud of the
homegrown Perl tools that he developed. Over time, he was able to put
together tools to gets classes, then methods, then functions, then
enumerations, then #defines, then...
The problem was that every new code type that we as writers felt needed to
be documented and exposed to users necessitated major changes to his tools.
It was a slow process. In this regard, I admit my inpatience; I wanted it
now.
Two employers later when I get the chance to get back into API
documentation, finding off-the-shelf tools was wonderful. They support
out-of-the-box all of the code item types that would generally need to be
documented for that programming language. I got decent output in a matter of
days for what it took this programmer five years to develop (imperfectly).
Hence, rather than you learning by trial-and-error "Gee, I guess the user's
really do need to know what this enumeration is or the inherited methods of
a parent class", the tools will already be exposing them. You're job then
becomes to either (1) brow-beat the engineers to write a description, (2) to
write the description yourself, or (3) to leave it without a description but
exposed [which can be perfectly valid when considering the intended
audience.]
In this manner, what the tools extract and expose is what gets added to your
outline. Those extracted code items are the "don't miss" information.
Again, we're only talking about reference material and reference
documentation.
Where it will help you, though, is when you see something unique being
extracted. Does it necessitate further research and explanation in the
"how-to" book?
HTH,
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 Anne
> Robotti
> Sent: Monday, May 07, 2001 8:34 AM
> To: TECHWR-L
> Subject: RE: API documentation?
>
> Glenn, what tools do you use to extract the code prototypes
> and comment blocks?
>
> I'm also working on documenting some APIs, and I'm feeling
> a little out of my league. Can you provide some pointers on
> "don't miss" information, so that I can make sure it gets in
> my outline?
*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com
Sponsored by Information Mapping, Inc., a professional services firm
specializing in Knowledge Management and e-content solutions. See http://www.infomap.com or 800-463-6627 for more about our solutions.
---
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.
