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.
Subject:Re: API documentation From:Jon Steiner <jons -at- AVI -dot- COM> Date:Fri, 7 Aug 1998 09:15:00 -0400
> Jennifer, Everyone,
>
> There are two packages that ease API documentation that I wanted
> everyone to be aware of:
>
> DocJet by TallTree (expensive, but in my experience, good)
>http://www.talltree.com
>
> AutoDuck by Microsoft (free, and source code is provided!): Unless you
> feel really comfortable marking up source code and are willing to slog
> through a command line environment, I'd try to get DocJet (depends on
> how generous your department is feeling.)
>
> DocJet will single-source your API - you'll be able to extract
> the necessary information from C++, Java and Visual Basic code, and
> publish it in HTML, HTMLHelp or MSWord format. (this is VERY good in
> itself. Saves LOADS of time.)
>
> So, my questions are:
>
> * How do you gather information for a project such as this? Is
> it normal
> to have to write this from scratch, or is it reasonable to
> request
> written information from the programmers that I can then
> rewrite,
> format, etc., and which would take a shorter period of time?
> [Jon Steiner]
> My advice here is use DocJet or Autoduck to create a first pass,
> and have the programmers fill in the holes. Don't allow them to put
> off answering anything, if possible.
>
> * Is my manager expecting too much too soon? Or am I expecting
> too
> little--that is, should I be accomplishing more, in a shorter
> time
> frame?
> [Jon Steiner]
> Don't managers always expect too much? ;)
>
> I had the same feeling, and these tools helped me leap from
> copying function calls from source code to RoboHelp manually to
> actually getting an overview of the product.
>
> On my first API documenting assignment, I crashed, burned, and
> received all customer documentation complaints. Now, I can call myself
> a programmer-writer with a fair degree of confidence...
>
> Good luck, Jen (and everyone else too!)
>
> _______________________________
> Jon Steiner
> Applied Visions, Inc.
> 6 Bayview Avenue
> Northport, LI, NY 11768
> (516) 754 4920 x 47
> (516) 754 1721 fax
> jons at avi dot com
>
