RE: About estimatiing API Documentation

["Glenn Maxey" <glenn -dot- maxey -at- voyanttech -dot- com>]

Hi Mandar,

Geoff's advice to you was sound.

Something else to [seriously] consider is a tool that can extract code
prototypes and maybe specially flagged code comments. I'm using Doxygen
freeware (www.doxygen.org).

>From my experience, the most important pieces of information that you
can give a reader/programmer is correct syntax to the API and the
meaning of the parameters (what is valid, etc.). 

Unfortunately, this is precisely the piece of information that the
programmers will be endlessly tweaking right up until AND THROUGH code
freeze. If you don't have tools/process in place, you will be forever
chasing after tweaks in the syntax of individual commands rather than
the big picture of how the commands are expected to work together, and
your documentation will be out-of-date as soon as a PHB gives the
engineers permission to fix a bug.

Process is one of the most important things you can help define that
will make this job easier (e.g., for every dinky little damn point
release, and there will be many.) You need management mandates and
engineering buy-off.

Every engineering organization that is worth its salt already requires
the engineers to comment their code, just another thing in their coding
conventions. Commented code is an asset to any organization even if the
code isn't an API. Hence getting support and buy-off for, say, a
modification to the code comment structure for integration with a tool
(e.g., JavaDoc, Doxygen) really isn't that difficult (depending upon
your corporate politics). However, someone such as yourself may be
tasked with the grunt work of following it through first time (after
you've earned the trust of engineering to modify their code).

If the reference material (API syntax, description, and parameter
description) resides in the code [where it belongs], much of the
documentation gets pushed to the engineers and the tools. The big
benefit is that if this information is in the code, it has half a chance
of getting updated by the engineer when they do their code tweak. You
become a part-time editor and enforcer on the reference material. When
not cleaning up flagged comments in the code, you can focus on other
aspects of the documentation set, such as installation, compilation,
overview, usage, grouping, EXAMPLES, etc. which reside outside of the
code.

As has been discussed on this list, tools are not the end-all-cure-all.
But by golly, they have sure saved my butt in the past when new,
deleted, and rearranged parameters came fast and furious. Tools have
allowed the tech pubs departments to boast a 99.997% accuracy of the API
syntax published in the documentation. (The percentage is much lower for
the descriptions, examples, etc.)

Glenn Maxey
Technical Writer
Voyant Technologies, Inc.
1765 West 121st Avenue
Westminster, CO 80234-2301
Tel. +1 303.223.5164
Fax. +1 303.223.5275
glenn -dot- maxey -at- voyanttech -dot- com


> -----Original Message-----
> From: Mandar Atmasidha [mailto:matmasidha -at- yahoo -dot- com]
> Sent: Wednesday, November 07, 2001 12:11 AM
> To: TECHWR-L
> Subject: About estimatiing API Documentation
> 
> 
> Hello All,
> 
> I need help regarding API documentation. 
> 
> I want to create API documentation for a Software
> Product. But I do not know how to estimate time for
> creating API documentation.
> 
> Can someone please tell me how to estimate time for
> creating API documentation?
> 
> Regards,
> Mandar

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