Estimating API documentation pages?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Mandar Atmasidha reports: <<I have found that in my API there are 2550
functions. Can someone please tell me how to calculate number of
documentation pages?>>

It's easier than you'd think. For the average function, figure out how many
sections you'll require to adequately document the function (e.g., "when
should I use this?", "when should I _not_ use this?", syntax, list of
switches or options, examples, related functions) then do a quick first
draft of your writeup for one function. This gives you an idea of how long
the average section will take. Obviously, a function that has many different
switches or settings will take longer, and one with fewer switches or
settings will be shorter, and that's why you want to pick a good,
representative function for this task. Now that you've got an average,
multiply this by the number of topics. Done!

<<Also I need some help in creating TOC for API documentation. Can someone
please tell me what goes in the API TOC?>>

First and most important, a table of contents gives a high-level overview of
the contents of the documentation: think of it as telling the reader
(quickly) "we have 5 chapters, with the following broad subjects". Thus, it
should contain all the major section headings (e.g., introduction,
explanation of your typographic conventions, group 1 of API functions, group
2 of API functions, etc.). Second, the TOC must give an overview of the main
topics covered under each main subject. Thus, under each of these main
headings, include the subheadings; for the groups of functions (e.g., group
1 = screen display, group 2 = control loops, etc.) you'll probably end up
with an alphabetic list of the API functions as your second level of
heading. If you've grouped the functions by task, so that the functions are
described in the same order you'd use them, then the list would follow that
order rather than being alphabetic.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html

"Computers are like Old Testament gods-lots of rules and no mercy."--Joseph
Campbell

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

Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ and check it out.

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