|
|
|
|
|
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, youll see not only where the nay-sayers above were right and but also where they were wrong.
|
|
|
Open-Source tools compliments of Voyant Technologies, Inc. and Glenn C. Maxey.
01/13/2003
TP Tools v2-00-0a
# tpt-hug-02