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:Scott Wahl <swahl -at- BRIDGEWATERSYS -dot- COM> Date:Fri, 7 Aug 1998 08:36:45 -0400
Hi Jennifer,
I am working right now on my first API document. Here are my thoughts.
Jennifer Rippel wrote:
> 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?
It is reasonable to expect some sort of document from the developers from which
to start your work -- if not a complete functional specification, at least a
technical note describing the functions and providing code examples. In my
case, I did a little bit of research (thanks again to everyone on this list for
their help) on what information I needed to include in the final document. I
passed this onto the developers, who wrote a technical note that included most
of the basic technical information: descriptions of the functions and their
parameters with code examples.
From this, I could fairly quickly create a customer document: I added more
descriptive and contextual information, did a thorough edit, and asked lots of
questions to fill in the gaps.
> * 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?
It sounds like your manager might be expecting too much in too little time --
but then again that's nothing new. Make sure you and your manager agree on the
quality and scope of the final document. Your expectations of what the final
product should look like may be out-of-sync. In my case, I got agreement from
the engineering and product managers that the customer required the document
very quickly, and that my job was to deliver a document, with the bare minimum
of information, as quickly as possible. I used a DRAFT watermark on all pages
of the document to make sure this was clear to the customer.
Hope this helps -- contact me offline if I can help further.
Regards,
--
Scott Wahl
Customer Documentation Coordinator
Bridgewater Systems Corporation
(613) 591-6655 x.2579
