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:Laura L Lapierre <lapierre -at- MEDIAONE -dot- NET> Date:Fri, 7 Aug 1998 10:28:32 -0400
It is very reasonable to request information from the programmers,
especially since they know best how the various functions work. Your
technical background comes in handy when you have to check their code to
make sure that is valid (or as valid as you can tell). Plus, you need to be
able to ask the right kind of questions (i.e. know what information you
need).
Do you have access to the source code? This provides (or at least should)
sample code, as well as contains the function declarations. This way you
know what functions need to be included.
Also, talk to the tech support person (if there is one) and find out what
questions people are asking. This type of information should definitely go
in your manual ... should help cut down on tech support calls.
> -----Original Message-----
> From: Technical Writers List; for all Technical Communication issues
> [mailto:TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU]On Behalf Of Jennifer Rippel
> Sent: Thursday, August 06, 1998 7:01 PM
> To: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
> Subject: API documentation
>
>
> 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
>
