Internship Report: Single-sourcing a Browser-based Help System
My internship project was essentially a
proof-of-concept for creating single-sourced help for the Connect ODBC drivers.
Existing Connect ODBC drivers have used the traditional Windows Help (WinHelp) since the products were
initiated. WinHelp provides some nice features
such as pop-up and secondary windows. With the release of Windows 98,
Microsoft announced their intention move to browser-based help (HTML help), and
not to develop any new features for WinHelp. However,
Microsoft continues to support WinHelp in Windows
applications.
Recently, a management-led buyout turned
our division into a separate company. This makes the upcoming Connect ODBC
release, which will include significant new features, an ideal time to switch
from using WinHelp to HTML help. Externally, the new
look would subtly emphasize that our technology is on the leading edge and
reinforce our new corporate identity. Internally, by single-sourcing from the FrameMaker files we use for the manuals, we would gain time
in our writing cycle, because we would not have to repeat the changes in a
separate help file. Single-sourcing would reduce the number of errors caused by
updating two baselines simultaneously. Reviewers in Development, Support, and
Quality Assurance would have to review only one set of documentation. In
addition, single-sourcing would result in considerable savings in translations.
Changing to HTML help would require a one-time investment of development time,
to modify the software to call the HTML files instead of using the existing
internal IDs for the help topics.
A WebWorks
template is already in place to create HTML help for the Connect JDBC drivers.
Unlike the Connect ODBC drivers, the JDBC drivers do not use a graphical user
interface for their configuration; the HTML help is not complex. Inevitably, in
my attempts to recreate the existing WinHelp design
in the HTML help, I encountered some situations that were not
covered by the template or by any in-house experience.
For this project, I did not change the
content to reflect the new company information or logo, and did not build the
help files with the drivers.
Existing Help System
Each Connect ODBC driver has its own
help file, which is displayed when a user clicks the
help button on a dialog box. In addition, we provide a general help file that
contains technical information that is common to all of the drivers. Users can
access the general help from the Connect ODBC program group. The general help
also provides an access point to the individual help files for all installed
Connect ODBC drivers. Figure 1 shows the general
help for a system that has the Oracle and XML drivers installed.
Figure
1. Connect ODBC General Help
Project Description
I
wanted to create a working model of HTML help that would closely resemble the
current WinHelp design. I began by applying
conditions to the XML driver chapter, to hide screenshots and other information
that did not belong in the help file.
The
XML driver chapter is probably the most complex chapter in the Connect ODBC
Reference. In addition to the standard configuration information, the
chapter includes new terminology and many technical concepts, such as how the
driver implements support for hierarchical files. It also uses some
non-standard layout elements, such as a cross-reference from conceptual
information to a step in the configuration procedure.
The
SQL section in the XML chapter contains three major subsections; the “Grammar
Token Definitions” subsection, in turn, includes 11 subsections. In the WinHelp topic, this is broken into separate topics. The WebWorks conversion, by default, would create one very long
topic. I added a paragraph tag that forces a new HTML page before each
subsection heading, and added a mini-Table of Contents similar to the WinHelp topic. The conversion process automatically adds
Next Page and Previous Page navigation buttons to each topic.
The
general help existed only as a Microsoft Word file in RoboHelp.
I had to reformat the text in FrameMaker and recreate
the index entries. I then created a help project for the General help and
fine-tuned the headings to match the WinHelp file.
With
the two projects created, I was able to set up the multivolume help system, the
WebWorks term for a help system that contains other
help systems. The setup specifies the order in which the tables of contents of
the component help files will appear, and merges the indexes from the
individual help files.
|
Standalone
Driver Index |
General Help Index |
|
Data source |
Data source |
The department procedure book includes a chapter on
using WebWorks Publisher to create an HTML version of
the manuals. My project plan included creating a new chapter to describe the
additional steps needed to create HTML help with WebWorks
Publisher. I tested my procedures by creating a help file for the Oracle
driver. Later, while trying to resolve a formatting problem that appeared in
the XML help file but not in the Oracle help file, I created a help file for
the Informix driver.
Figure
2 shows the completed project, with the Table of Contents opened to display the
topics in the General help and the XML driver help.
Figure 2. HTML Help
Development Adventures
I
had to solve several challenges when developing the HTML help project. Several
problems were caused by missing information in the
template and in the WebWorks manual. One problem
involved a strategic decision on how to organize the information.
Solving Software Problems
The
XML driver chapter, and the existing WinHelp file,
include a table with check marks made using ZapfDingbats.
Because the current HTML help template does not include a mapping for ZapfDingbats, the check marks were
instead converted to “3”. Chris Walker, our WebWorks
expert, had corrected this problem in the template for the HTML books. Luckily,
he remembered the two-step process, which was not clearly
defined in the WebWorks documentation. (
In
our existing WinHelp files, we use pop-up windows for
definitions and for short descriptions, such as a bulleted list of Windows
releases supported. Adding pop-up windows to the HTML help was difficult,
primarily because the WebWorks Publisher manual left
out a critical preliminary step—you must add the cross-reference in the FrameMaker file before starting the procedure in the
WebWorks manual. (WebWorks)
This information also promptly went into the “Troubleshooting” section.
Once
I had created the pop-up window, I found that if you click the link instead of hovering the mouse over the link, you go to the actual
definition. I decided to create a small “Definitions” topic for the help file.
I created a new heading paragraph style that would not appear in the Table of
Contents, and placed it at the end of the FrameMaker
file. I set the HelpExpose condition on the pop-up
link, and added text that will be displayed only in
the PDF and HTML books. (See the “SQL Statements for XML File Formats” topic in
the XML driver help for an example of a pop-up definition.)
As
with the pop -up windows, creating the multivolume help was more difficult than
it should have been because of missing information in the WebWorks
manual. The WebWorks conversion produces three
folders: Output, Support, and Temporary. The WebWorks
manual says that to create the multivolume help, you have to map the output
folders for each project to a common directory. (WebWorks)
Unfortunately, the manual didn’t say how to do this. I assumed,
incorrectly, that the mapping was done in Windows
Explorer, and spent several fruitless hours trying to create the Contents pane
in the help file. Once I found the correct field on the Options tab of the WebWorks project, the task was straightforward.
One
formatting problem occurred only in the XML driver help. In Figure 2, notice
that an extra heading, “1 Connect ODBC for XML”, has been added during the
conversion. I have been unable to correct this, but it does not interfere with
the function of the help file. I am continuing to pursue this issue with our
in-house expert, Chris Walker.
Skirting Around Single-Source
In
a true single-source system, information would appear only once in a file, and
would use conditional text or similar coding to present information into the
necessary formats. Some experts recommend instead duplicating some information
to avoid an overly complicated system of conditions. (Prendergrast)
I chose this method several times, creating separate topics coded with the HelpExpose condition. In one case, the text in a conceptual
section contains a cross-reference to a spot inside a procedure—creating a
separate topic was a much cleaner solution.
In
the other cases, I needed one topic for configuration procedures in the manual,
and separate topics for each dialog box. The existing help topics for the
dialog boxes are not written in procedural form.
Instead, they briefly describe the fields and controls on the dialog box. The
content is similar, but the writing style is different. (For an example,
compare the “Configuring Data Sources” topic and the “General Tab” topic in the
XML driver help.)
In
a true single-source system, we would generate the online help from the FrameMaker files that were used to
generate the final book. We would check the files into our version control
system, and then check them out again to generate the help. This would ensure
that the book can be recreated, regardless of tweaks
to the file required to correct problems in the HTML help. At present, we copy
the FrameMaker files to a separate location, and
generate the help files from this copy, to avoid any chance of causing problems
in the source files for the books. Setting up the version control structure
correctly is very complex (and is beyond the scope of this project). We need to
investigate the issues and design an appropriate structure.
Results
My
proposal was to create a working HTML help file for the XML driver, using the FrameMaker file as a source, similar in design to the
driver’s WinHelp file. The HTML help includes both a
driver-specific file that could be accessed from the
help buttons of the setup dialog boxes, and a general help file that is
accessed from the program group. To better simulate a real world scenario in
which users install several drivers, I created help files for the Informix and
Oracle drivers as well. I also created a new procedure for the department
procedure book, describing the steps required to produce the help project
Now
that we have a procedure and have identified many of the likely conversion
problems, it seems very likely that we can convert the Connect ODBC manual into
HTML help files in a straightforward manner. We need to test the files with the
drivers. Within our group, we need to evaluate the new paragraph and
cross-reference styles that I created, and decide whether they need to be modified before they are added to our FrameMaker
template. We also need to decide how to handle version control on the files.
Works Cited
Adobe. Using FrameMaker 5.0. 1996.
Prendergrast, Alexia. Lecture, STC.
Quadralay. WebWorks Professional Template Reference. Pages 96, 104, 108.
Walker, Christopher. Interviews, various dates.