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

Reality Check

Whereas all of the points against single-sourcing and against using tools (to produce API reference material) are valid, the counter arguments are more sober because they reflect reality.

• Technical writers are being asked:

» (hurdle 1) to produce documents in various output formats. (Single-Sourcing).

» (hurdle 2) to update the information in each of those output formats from release to release. (Maintainability).

» (hurdle 3) to re-purpose and re-use much of the same information in different manuals and in different output formats. (Re-usability).

» (hurdle 4) to streamline the process to improve the accuracy and reduce the margin for human error. (Automation).

» (hurdle 5) to keep our customers up-to-date with the latest changes to the documentation. (Web-Updatable).

• Aside from everything else we write, many of us are being asked:

» (hurdle 1) to document APIs in (unfamiliar) programming languages.

» (hurdle 2) to maintain this API documentation for a fast changing code pool in a development environment with frequent releases.

The rants that follow try to provide some real-world common sense to our plight before plunging into the details of a cost-effective solution that can help us achieve our buzzwords.

• single-sourcing

• maintainability

• re-usability

• automation

• web-updatable

If you ignore the rants (not a bad idea), go directly to the next chapters, and put these open-source techniques to use in your environment, you’ll see not only where the nay-sayers above were right and but also where they were wrong.



 "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