Logo Left Logo RightFREE TrialsOrder Now

hb_banner.gif (2375 bytes)
rule.gif (877 bytes)



Creating Online Help and Printed Documentation from the Same Source

What exactly does it mean to use a single source for both online and printed documentation?

True Single Source vs. Simple Conversion

What are the arguments for using a single source approach?

The “Print to Help” Single Source Model

Is the “Print to Help” Approach Backwards?

The Single Source Model in HelpBreeze 3.0

rule.gif (877 bytes)

What exactly does it mean to use a single source for both online and printed documentation?

Developing both printed and online documentation from the same source simply means that you create and  maintain only a single set of documents in order to produce both formats. It DOES NOT mean that the online and printed versions must be exactly the same; in fact, they may be very different. A good single source tool will include features which allow you to specify exactly what will be included in each medium.

Single source tools generally designate one format (either printed or online) as the primary medium. All authoring is done in the primary medium. In order to create the other (secondary) medium, the tool will perform an automated conversion.

True Single Source vs. Simple Conversion

Many help authoring tools offer one- or two-way conversion between Windows Help and printed documents. This is generally not the same as a true single source approach.

In a single source tool, all the information necessary to generate the secondary medium is embedded in the primary medium. This means that if you maintain your project in the primary medium, you can automatically produce a corresponding version in the secondary medium—and you will have to do little or no manual manipulation in order to get it into its final form.

Tools which offer only conversion capability don’t go this far. For example, a “help to print” utility might strip out all the special formatting used by the help compiler. However, in order to get the resulting document into a final format for a printed manual, you would still need to do a lot of work, such as applying appropriate heading styles, reformatting text, customizing the text and graphics to be appropriate for the printed medium, adding page numbers and a table of contents, etc. As a result, after completing the conversion and the required editing, most authors would choose to maintain two separate sources from that point on.

What are the arguments for using a single source approach?

  • Nearly all documentation authors have to work within the realities of economic and time-to-market constraints. In many cases, both the online and printed documentation may have to be created and maintained by a single individual or a small team. In such a case, a single source approach will very often result in a faster and higher quality result. If the documentation must be maintained over a long period, the savings in time and resources will be even more substantial.
  • Maintaining a single source helps insure consistency in your documentation and reduces the likelihood of errors resulting from the fact that both versions are not maintained identically.

The “Print to Help” Single Source Model

Most single source authoring tools use a “Print to Help” approach. The leading tool of this type is Doc-To-Help® by WexTech Systems.

With this approach, the printed document is the primary medium. The author creates a printed document using the special template and/or tools provided. Then, when the author is ready to create the online version, he or she initiates a conversion process in order to create the Help file.

Is the “Print to Help” Approach Backwards?

Just a few years ago, most software products shipped with a thick manual and minimal online help. Now the situation has reversed itself; in many cases, the primary documentation is now online and the manual has become a “getting started” booklet. A similar process is occurring with internal organizational information.

Think about why organizations are putting all kinds of information online:

  • Because online information is easier to maintain—and much less expensive to distribute.
  • Because online information offers unique features—such as search capability, multimedia and integration with other applications—which are not available in printed documentation.

What are the implications of this for the author who needs to create and maintain both online and printed versions of documentation? Which medium will need to be updated more often? Which medium will be considered the primary reference resource? The answer is likely to increasingly be: the online version.

Given this fact, does it make sense to use a tool which forces you to maintain your original source in printed document format? Consider some of the problems associated with the Print to Help approach:

  • For large projects, the Print to Help conversion process can be lengthy—in some cases, it may take hours. That means that any time you make any change to your original source, you have to wait for the conversion before you will have a Help file. Because most Print to Help tools provide no way to preview or emulate the Help file prior to the conversion, you won’t know how the final product will look until the process is complete.
  • Often, Print to Help tools don’t give you complete flexibility because the structure of the Help file is derived directly from the printed document, usually by examining the heading styles. The implication of this is that, although most tools will allow you to specify that various material will appear only in the Help or only in the printed version, the basic structure of the Help file must still follow the printed document original.
  • Windows Help has evolved into a medium which is far richer than the printed page. Interactive elements such as multimedia, the ability to run and control applications, and direct links to Internet web sites have no parallel in the printed medium. With a Print to Help tool, you must “hide” the information necessary to create these elements in the printed document so they will fall into place during the conversion process. This is a needlessly cumbersome approach which deprives you of an opportunity to author and test these advanced features interactively.

The Single Source Model in HelpBreeze 3.0

HelpBreeze has, since its introduction, been geared primarily toward interactive Help file authoring. Version 3.0 introduces a unique new tool called the Document Wizard, which offers a “Help to Print” single source approach.

Using the single source support in HelpBreeze 3.0 is a three-step process:

  1. Create, test and compile your help file in HelpBreeze’s WYSIWYG authoring environment. As you author your Help source files, you can specify that material should appear only in the Help file or only in the printed document.
  2. Use the Document Wizard’s Visual Outliner to design an outline for your printed document. Designing the outline is a point and click process.
  3. Use the Document Wizard to create a fully-formatted printed document automatically. Once you have created an outline and selected options for the Help to Print conversion, you can repeat the process in order to create an updated printed document at any time with a few clicks of the mouse.

Consider some of the advantages of this approach:

  • Since the online version is the primary medium, you can use HelpBreeze 3.0’s interactive, WYSIWYG authoring tools to create and test your Help file. There is no long conversion process to produce a Help system. You can start the help compiler with a single click of the mouse. And because HelpBreeze provides extensive WinHelp emulation capability, you don’t even need to compile in order to test most Help features.
  • Because the printed document is created based on an outline which you design, you have absolute control over the structure and content of both the Help file and the printed document. They can be as similar or as different as you want them to be.
  • You can automatically produce a professional-quality printed document. You have complete control over attributes such as paper size, margins and styles. You can use advanced features such as margin notes. The Document Wizard will automatically create a title page, table of contents and index—all of which can be fully customized.
  • There are numerous options for customizing your project for the target medium. Text ranging from a single word to an entire chapter can appear in only one format. You can use completely different graphics in the Help file vs. the printed document. For example, you might include screen shots in the manual, but not in the Help file.
  • By maintaining your original in Help format, you can take advantage of the many features in HelpBreeze which are geared toward navigating in your documents, managing large projects and sharing information among multiple authors.
  • Many authors need to create both printed and online documents for some projects, but for other projects they need only the Help file. The Document Wizard is there if you need it, but it won’t get in your way if you are only interested in producing a Help file. You can even change your mind later…
  • The Document Wizard can be used to produce a printed document from any Help project—even if the project wasn’t originally intended to serve as both online and printed documentation.
  • If you already have a printed document, HelpBreeze can automatically convert it into a Help topic file based on the heading styles. After converting your document, you can use HelpBreeze’s interactive features to refine and maintain it. You can then use the Document Wizard to generate an updated paper document at any time.

rule.gif (877 bytes)

(c) Solutionsoft
All Rights Reserved.