|
|
|
|
|
Manuals created from auto-documentation tools may not always be as complete or as easy to read as those manuals created by hand. The counter arguments to this are:
If your organization presently has no API documentation, source code extraction tools give you a significant head start.
Even those wonderful, easy-to-read, manually created API documents did not evolve overnight into completeness. If your tool has holes in its coverage:
» You manually document the holes in the system and let the tool help do everything else. Dont re-invent the wheel.
» You can have your software development organization enhance the open-source tools to achieve what you need.
Completeness is relative.
» Many times the code item name and its syntax are descriptive enough to the audience when viewed from a header or source file.
» If the code items that the audience is expected to use are well documented, the documentation may not need to be as complete or as detailed for other code items that might be exposed.
» The API evolves and so does the documentation. Do what you can when you can, and let feedback from others (internal and external to your company) help prioritize what needs to be improved.
» The completeness of the API documentation can be a recursive process.
With the appropriate company processes in place, the same excellent writing can be achieved regardless of where the information resides.
|
|
|
Open-Source tools compliments of Voyant Technologies, Inc. and Glenn C. Maxey.
01/13/2003
TP Tools v2-00-0a
# tpt-hug-02