RE: Estimating API Documentation pages [long]

["Lydia Wong" <lydiaw -at- fpoint -dot- com>]

[cross posted to the API Tech Writers listserv group]

Mandar asked the following on TechWr-L:

> I have found that in my API there are 2550 functions.
>
> Can someone please tell me how to calculate number of
> documentation pages?
>
> Also I need some help in creating TOC for API
> documentation. Can someone please tell me what goes in
> the API TOC?

That is a large number of functions! We document APIs for our products, but
none of them have that many functions. We create our documentation "from
scratch"--that is, by analyzing the products (Windows GUI components) and
the source code for them. We write in FrameMaker, and output to print, PDF,
and online help (using WebWorks Publisher).

However, for that many functions, if I were you I'd definitely look at
document generation tools, as Glenn Maxey suggested. There are many tools
available, varying in price from free (freeware) up to several hundred
dollars. The tools vary in terms of what type of source code they will work
with (source written in C/C++, Java, etc.) and in their output (Word/RTF,
WinHelp, HTML, HTML Help, etc.).

A friend of mine presented at our local STC chapter meeting and at the
national STC meeting last year a talk about document generation tools for
API docs. Here's a link to the local chapter web site that makes his
presentation and some additional materials/links available:
http://www.stc-carolina.org/www/PICs/online/OnLibrary.shtml

As for estimating the project and the number of pages, there are many
variables involved. Someone who uses a document generation tool would be
better equipped to give you an idea of the time needed to implement the
process and generate documentation. Your number of pages is going to vary
greatly depending on the complexity of your functions (the number of
parameters, how many other functions it works with or relates to, etc.), the
layout of your final documentation, and your time.

Once you have your documentation "template" that Geoff Hart described, that
will give you a good idea of what you need to generate if you choose to use
a document generation tool, and how much of the information will be coming
from developers vs. material you must research and create. Don't forget the
good advice about writing and including examples as well. Most users want a
LOT of examples, so factor in some time to write them or coordinate the
writing of them with your documentation work.

If you'd like to see some API documentation, you can download a 30-day trial
of one of our products from our website at www.fpoint.com. Once you install
the trial version, from the Start->Programs menu choose the product name.
There will be menu items to access the online help file for the product. You
can see our help file TOC to get some ideas about API documentation
formatting and organization.

HTH,

Lydia
---------------
Lydia Wong
Technical Writer
FarPoint Technologies, Inc.
www.fpoint.com


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Be a published author!  iUniverse gives you: a high-quality paperback, a
custom cover design, and distribution to 25,00 retailers.  Join our almost
10,000 published authors today. http://www.iuniverse.com/media/techwr

  Your monthly sponsorship message here reaches more than
  5000 technical writers, providing 2,500,000+ monthly impressions.
  Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

---
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.