Contents 
 Index 
 "TPT User's Guide" 
 < Previous 
 Next > 

API Documentation Naysayers

When the single-sourcing discussion is extended to API documentation, again the opinions vary. If you ignore tutorial, overview, and how-to material and focus only on the reference information, the points of contention are:

• Can source code extraction tools (auto-documentation) generate your reference manual?

• Where should the information for reference manuals reside?

» In the source code?

» In documents separate from the source code?

• Who should maintain the reference material?

» The technical writer?

» The software engineer?

One side of this argument say that tools cannot get you your API manual. For various company-specific technical and political reasons, they say that the information needs to be maintained separate from the source code by the technical writer.

• Manuals created from auto-documentation tools that extract prototypes and comments from the source code were not as complete or as easy to read as those manuals created “by hand.”

• The tools can generate documents that have accurate code prototypes, but don’t generate code examples or prolific explanations.

• The source code contains very little information. You get data points, lists of code items and their classification, but little description of what they do, what they mean, or why they are the way they are. Neither the code nor the code comments explain the API to an external user.

• Software engineers shouldn’t write the API reference material because:

» They don’t have the time to step back and think about the code from an API-user’s perspective.

» They barely have time to comment their code about why something was implemented the way it was.

» They can’t write, don’t like to write, or aren’t allowed to write the information in a polished manner.

» They might not even have English as their native language.

» Whatever they write must be heavily edited.

• Although the software engineer may know (a) what features have been added, (b) why you would use them, and (c) how you would use them, this information rarely resides in the commented code.

• Auto-documentation tools require a level of trust that the software engineers are keeping their code comments up to date.



 "TPT User's Guide" 
 < Previous 
 Next > 


Open-Source tools compliments of Voyant Technologies, Inc. and Glenn C. Maxey.
01/13/2003

TP Tools v2-00-0a

# tpt-hug-02