Managing help when multiple tools are in one GUI

Subject: Managing help when multiple tools are in one GUI
From: Kate Stout <stout -dot- k -at- comcast -dot- net>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Sat, 16 Oct 2004 07:51:25 -0400

In a project I did for a company that created software to support supply chains, I had essentially the same requirements, with the additional wrinkle that there were html documents generated from some development files that had to be included and indexed as well.

I used Webworks (not a plug, it was there when I got there) to create different help systems - Webworks allows you to point to a source directory for Word or Framemaker files, and then does a conversion to html (or other formats) and create appropriate navigation and indexes. SoI had a project for each of the standalone products, and then a project for the "big integrated product" that contained all of the source directories. In the integrated project, I also had a short series of overview material that lead you into the different aspects of the product (i.e. provided quick navigation into the various products), and made that the default startup page of the help system.

A lot of the work was actually accomplished through the nightly build process. The biggest issues were version control, version numbering, and source code/help system synchronization.

Let's say you've got the integrated project OneGUI, which consists of three little GUIs, BuyingGUI, SellingGUI, ReadingGUI.

OneGUI is at version 1.0, but the little GUIS are all version 6.0, which reflects their history. The build pulled source documents from the individual trees for the little GUI projects. If this was a build for OneGUI, a script was run to ensure that all the VersionNumber variables were at 1.0. Similarly, a script was run to ensure that the correct product name was used: OneGUI, rather than the BuyingGUI name that was used if the product was standalone. Imagine that there are lots of little details like this - you spend a lot of time making sure you've got all variables/tags set up properly.

Then the Webworks conversion tool was used to generate the help systems. (You could substitute your process of choice here.) Finally, we ran a tool across that help system to ensure that there were no broken links.

Once a week, we ran another tool across the source code and generated help files to ensure that all source code links to help had a corresponding help topic. This particular company had a fairly complex scheme based on UI page IDs that were stored in an external file, and depending on whether you were in the OneGUI or the little GUIs, the HelpID was constructed differently. This was one of the most vunerable places in the system, and a lot of our problems were in this area.

Since most of the work was done through the build process (after you've done the massive work of getting variables set properly), it was possible to pull a version of the product from the source tree and generate the appropriate code and matching help system for either the OneGUI or the little GUIS.

To do this, obviously you will need a fair amount of support from both the development and build team.

Kate Stout

Making things clear.....
Technical Writing Services


ROBOHELP X5: Featuring Word 2003 support, Content Management, Multi-Author
support, PDF and XML support and much more!

WEBWORKS FINALDRAFT: New! Document review system for Word and FrameMaker
authors. Automatic browser-based drafts with unlimited reviewers. Full
online discussions -- no Web server needed!
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit for more resources and info.

Previous by Author: Re: fiction manuscrips being unpublishable for "not being creative en ough"
Next by Author: About Data Flow Diagrams
Previous by Thread: Re: Managing help when multiple tools are in one GUI
Next by Thread: RE: Managing help when multiple tools are in one GUI

What this post helpful? Share it with friends and colleagues:

Sponsored Ads