Single Sourcing Your Help |
  
|
Single Sourcing Your Help |
|
Peter Vogel Gold Collection
If you're creating an application, you really should create some support for your users–a Help file and a user manual are the least that you could do. If you're an Office user, DocToHelp from ComponentOne is probably your best choice for creating both–and you only have to create a single document.
In the technical writing field, "single-sourcing" refers to the process that uses a single initial product to generate all of your documentation. DocToHelp from ComponentOne (www.componentone.com/productmain.aspx) provides a single-source solution for developers who are familiar with Microsoft Word: The single initial product that you create is used to generate both your Help file and your user manual.
Using DocToHelp is relatively straightforward. After installing DocToHelp, you click on the Create New Project link on the start page. This starts a wizard that guides you through the project creation process. You first select (or create) a folder to hold your Help project and then create a new DocToHelp project file. The wizard then prompts you to pick a template for your document and the default format for your online Help (in addition to the Microsoft HTML Help format, DocToHelp supports several other Help formats). When you click the Finish button of the wizard, DocToHelp opens the Word document that you'll create your manual in and you can start typing.
Creating a Help system and a manual now consists of using the standard Microsoft Word tools: You type, you format, you save your work. The predefined heading formats (easily accessible from the DocToHelp toolbar) provide the markup that the Help creation process will need. The heading level 1 and level 2 formats, for instance, mark out the "books" in the Help table of contents, while the heading level 3 format marks out the topics within those books.
You can go beyond the Word basics, if you want. There isn't room here to discuss all of the features that DocToHelp supports, but three stand out because they're essential for creating a professional-looking Help system.
The glossary function stands out for me because of its ease of use. To define a term in the glossary, you select a word (or phrase) in your document and click on the Add Glossary Terms button. This brings up a dialog where you can enter your definition. When you generate your Help file, every appearance of the term will automatically be set up as a hyperlink to the glossary entry. When users click on a defined term in your Help file, your definition will automatically pop up. Your glossary is kept in a separate Word document, so you can open that document and upgrade the basic definition by, for instance, adding graphics.
You can also add links between the topics in your Help file. Implementing this is as easy as creating your glossary, provided that you've written the topics that you want to create links between (or, at least, inserted the headings for those topics). To create a link, you select some text in your Word document and click on the Add Topic Link button. This brings up a dialog box of all the topics in your document–select the topic that you want to link to and the link is created.
The other essential tool (among many other tools) is the ability to mark out conditional text. Conditional text allows you to select some text in the printed manual and omit it from the online system (installation instructions, for instance).
When you're done, you click on the Build button on the toolbar to generate your printed manual and HTML Help system. If I have one complaint about DocToHelp, it's that the error report that's produced by the build process (a typical error occurs when I delete a topic that's linked to from somewhere else in my document) doesn't make it as easy to track down my errors as I'd wish.
The only thing that DocToHelp doesn't do for me is generate a PDF version of my manual. For that, however, I use Win2PDF, so I can do that also.
In the download for this article, I've included four documents from a recent project: the initial file that I created with DocToHelp, the CHM online Help file, the printed user manual, and the PDF file generated from the Help manual.
Your download file is called 502VOGEL.ZIP in the file SA2005-02down.zip
This is found in the Gold Collection on this page
Note: Garry Robinson uses Help and Manual to single source his help and this build this website