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
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:
- 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.
- Use the Document Wizard’s Visual Outliner to design an
outline for your printed document. Designing the outline is a point and click process.
- 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.
|
