Managing help when multiple tools are in one GUI

[Kate Stout <stout -dot- k -at- comcast -dot- net>]

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
http://www.katestout.com
---------------------------------------------------------


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ROBOHELP X5: Featuring Word 2003 support, Content Management, Multi-Author
support, PDF and XML support and much more!
TRY IT TODAY at http://www.macromedia.com/go/techwrl

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! http://www.webworks.com/techwr-l 

---
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
http://www.techwr-l.com/techwhirl/ for more resources and info.