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

Scope of TechPubTools

This document describes some techniques and tools for single-sourcing and application programming interface (API) documentation or software development toolkit (SDK) documentation.

Single-Sourcing

If your interests are just single-sourcing, what is presented here can assist you in creating an HTML system that is modular and scalable. This assumes that you are using FrameMaker as the source and that Mif2Go or WebWorks Publisher generate mini-HTML systems for your books.

What these tools do is wrap all of these individual systems into one comprehensive system with a table of contents, index, and links to associated PDF files. They make it easier to create modular systems.

API Documentation

If your interests are just API documentation, what is presented here can assist you in creating an HTML system that is modular and scalable. This assumes that you are using code files as the source and that Doxygen or JavaDoc generate mini-HTML systems for your API or SDK projects. What these tools do is wrap all of these individual systems into one comprehensive system with a table of contents, index, and links to associated PDF files.

Extend Me

Although the TechPubTools and techniques were designed specifically for C/C++ API documentation, they can be adopted and modified:

• to handle other programming languages.

• to produce large online documentation systems from multiple FrameMaker books.

Proof of Concept

Experience taught me that modularity should be built into the TechPubTools from the onset in order to save much re-work and re-design later.

Since starting on this project (October 2000), I have employed them and refined them in over 18 separate master projects as of January 2003. Most of the 18 separate projects are still being maintained.

• On the average, each project contains at least three (3) sub-projects from FrameMaker and at least two (2) sub-projects from Doxygen.

• My largest project has two (2) sub-projects from FrameMaker and 38 sub-projects from Doxygen.

• Interestingly, nearly all of the 18 projects contain at least one or two sub-projects that are duplicates, although my source files (and even HTML directories) have not been duplicated. I use symbolic linking and the modularity and flexibility in the tools to publish-it-in-one-place and expose-it-in-many-places.

Although I firmly believe that you can’t provide a reader with too much information, I do concede that sometimes too much information in one venue can be overwhelming. Breaking a project into modular components permits re-use of those components in other settings when relevant.

• In one case, I have a comprehensive project with some 40 sub-projects that publishes everything I know about that project.

» The comprehensive view is of interest to the owning engineers.

» For some of the down-stream internal users, need-to-know issues came up as well as noise in the index and table of contents.

» I created separate projects and symbolically linked various sub-project directories in order to generate smaller, focused views of different areas of the project.

• In several cases, individual components of various projects are useful for other related projects.

» Certain manuals are needed by both internal and external audiences

» Certain internal audiences require different levels of details or components from one or more projects.

» I maintain everything about the smaller project in one location. Then I build up larger projects by symbolically linking to component directories of various smaller projects.

Working smarter and not harder.



 "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