Re: API documentation

[Craig Sanders <csanders -at- ONLYXLNT -dot- COM>]

Hi, Jennifer!

One of the very first things I would suggest you do is start encouraging the
developers to comment the daylights out of the code they write. If they are
using one of the newer development environments, such as Visual C++, you can
get access directly to the code via SourceSafe, and then read the comments
directly. I have found this to be very helpful in the past. Once you have
gotten the developers "comment trained," start encouraging them to write
examples for each method. This will make your job, and ultimately theirs as
well, much, much easier. The major selling point is that if they comment their
code and produce examples, the actual time they spend doing this will be
considerably less than the time they would have spend explaining it to you.

Hope this helps,
Craig Sanders

Jennifer Rippel wrote:

> I am a rather new technical writer, and my first project is to document
> the API for a library of C++ functions.
>
> So far my information-gathering process has consisted of programmers
> verbally explaining the various classes and functions to me. I then have
> to write the documentation from scratch.
>
> Although I have a good technical background and a good background in the
> subject matter, the concepts are still new to me. Therefore it takes a
> long time (reading about the subject, looking through the code, then
> writing, revising) just to produce a few pages of documentation. I've
> worried that this process has been going too slowly, but on the other
> hand I'm not sure how I could go any faster.
>
> Today, a manager also expressed concern that this project was going too
> slowly.
>
> 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?
>
> * 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?
>
> Thanks,
> JR
>
> jlrippel -at- hotmail -dot- com
>
> ______________________________________________________
> Get Your Private, Free Email at http://www.hotmail.com
>
> From ??? -at- ??? Sun Jan 00 00:00:00 0000==



--


"We do not see things as they are...
we see things as we are."
 -Anais Nin


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=