Creating Online Help in RoboHelp from a User Manual in FrameMaker
by Ron Kurtus (revised 24 March 2001)
Many technical communicators are tasked with converting user manuals and
other documentation written in Adobe FrameMaker into online help using
Adobe RoboHelp (formerly from Macromedia). The problems they face concern
not only going from FrameMaker to RoboHelp but also how to put the content
in a form that is effective for online help. The solution is not difficult,
provided the writer follows a methodical approach.
Questions you may have include:
What do you need to know before converting the manual?
What is the process of converting to RoboHelp?
What is a way to develop a help project?
This lesson will answer those questions. There is a
mini-quiz
near the end of the lesson.
Background
After writing a large user manual in FrameMaker for a Wisconsin-based software
company, they decided they needed online help for their software product
and wanted it done in RoboHelp. This paper provides a case study of the
process used to create online help for their product, including the relationship
of their product and its user manual, how I converted FrameMaker to RoboHelp
and how I developed online help content from the user manual.
Relationship of product and manual
It is important to know what the product does and what its user manual
is supposed to achieve before proceeding to the development of the online
help.
Job costing product
The user manual was written for a job costing software application. This
product helps service companies-such as in the construction industry-monitor
the costs of their projects. It allows managers to keep track of such items
as material, labor, and subcontractor fees. The application's menu system
is arranged according to job cost functions or activities of the user. The
menu opens numerous windows or forms for entering or viewing data.
This is a complex application that allows the user to drill down on data
in a window and go to sub-windows for further detail. There are over 200
windows available for displaying job data, and each window requires its
own procedure in the user manual. The structure of the manual is based on
the hierarchical arrangement of the application's menu system.
User manual in FrameMaker
The FrameMaker book was divided into files for each of the major areas
of the menu, such as job maintenance, entering transactions and viewing
job status. This arrangement-with the descriptive naming of the files-was
also applied to the help project. The continuity of file names used in the
manual and online help proved useful in keeping track of material.
The purpose of our user manual is to show how to use the numerous job costing
windows, as well as the navigation between them. The manual is approximately
450 pages long and has over 250 sections. Most of those sections include
a procedure, with several screen shots. When put into WinHelp, each section
results in one or more help topic.
Before starting, special paragraph styles were used in the FrameMaker book
to maintain consistency and to aid the documentation, and fonts were selected
for aesthetic appeal. During the writing, words and phrases were marked
for indexing. This was very important, since the index is the most used
feature of online help. Indexed items in FrameMaker automatically follow
the conversion into RoboHelp.
Converting files to RoboHelp
The process of converting a book written in FrameMaker to the format suitable
for using with RoboHelp is relatively straightforward. It consists of converting
the FrameMaker files to Microsoft Word and then reformatting the text in
Word to make it easy to use in RoboHelp.
Converted FrameMaker files to Word
If a FrameMaker file has any pictures or graphics included, you cannot
easily convert that file to Word. Since our manual includes of numerous
screen shots, as well as small graphics to indicate such things as mouse
movement and warnings, it was necessary to strip all of them from each FrameMaker
file. Many of those graphics would probably not be used in the online help
or would not fit into the help format, so their removal was not a problem.
Once the graphics were removed, I simply saved the files as Word files.
The process was painless, unless a graphic or two was accidentally left
in. Since I had previously named the FrameMaker files to reflect their function,
the name of the Word files would remain the same.
Reformatted files for use in RoboHelp
Paragraph and font styles from FrameMaker files carried over into Word
files. When a Word file is then converted to RoboHelp, the existing font
sizes and types are maintained. Each heading is automatically changed to
Heading 1 and is made a topic title for the online help.
I wanted to get rid of all the paragraph styles used in the FrameMaker
files and make the Word file as "clean" as possible. That may
not have been necessary, but I felt getting rid of all the old baggage would
prevent potential problems. I changed all the styles, except the headings,
to Normal with a font of Arial 9. This would conform to the style commonly
used in WinHelp. I also changed all the heading files to Arial 12 for automatic
topic construction in RoboHelp.
Developing help project
Once the files were converted to Word, I created a help project, selecting
the WinHelp 2000 option in RoboHelp version 7. Two important innovations
in this help project were using the outlining feature of Word to aid in
organization and changing major procedures into graphics with popup explanations.
Used WinHelp 2000
We decided to use the WinHelp 2000 feature of RoboHelp 7 instead of the
standard WinHelp 95 format, since that is the look of the future. WinHelp
2000 appears like Microsoft's HTML Help, which is used in Window 98 and
Office 2000 products. The only difference-which is also an advantage-is
that WinHelp 2000 is still based on the Windows 95 help engine, thus avoiding
possible compatibility problems.
WinHelp 2000 seems easier to navigate than WinHelp 95 since the contents
are always available in what they call the Explorer view. Another big advantage
of using WinHelp 2000 is that online help is easier to create. You do not
have to designate the type of window that a jump goes to. Secondary windows
are not used in WinHelp 2000.
A nice feature in WinHelp 2000 is that you can add a graphic as a watermark
to your non-scrolling areas. I inserted the company logo as a watermark,
such that it displayed to the left of every topic title. A disadvantage
of WinHelp 2000-as well as HTML Help-is the fact that the help window is
typically much larger than in WinHelp 95 and often covers the view of your
application.
Outlined Word files
When you create a new topic in RoboHelp, the topic title becomes Heading
1 in Word. I wanted to be able to distinguish between major sections and
their subsections when working in Word, to aid in the organization of my
material, but I did not want those topics to look any different in the online
help. I used the outline feature of Word, changing the headings of subsections
all the way down to Heading 4. This made the section organization very similar
to the user manual.
I reformatted the font style of Headings 1 - 4 to be 12 point Arial. Thus,
I could examine the outline in Word and easily reorganize the position
of the files. This would not affect anything in the online help, but it
made it easier to keep things in logical order. I also made the headings
light blue to add a little pizzazz and to look good with the company logo
in the non-scrolling area of the topic window.
Went from procedures to pictures
In trying to simplify our procedures for filling out the various job-costing
windows, I realized that in many cases using procedures was not the best
way to do things. Also, some of the procedures were well over 10 steps long,
which makes them difficult to follow.
Look to user's needs
I realized that the user does not need numbered instructions to fill out
text fields or to click on certain buttons. Rather, the person would like
to know what specific items mean and what happens if you use the item. Thus,
I decided to replace major procedures with a reduced size picture of the
window in question and use popup windows to explain each item in the window.
Some of those popup windows would include a jump to another topic or choices
of other popup windows for more detail.
Outlined popups
After it was made into a topic in RoboHelp, each popup window was outlined,
as a Heading 6 in Word and the font was set as Arial 9 bold. The "keep
with next" paragraph feature was turned off for the popup titles to
display in the help. The popup windows were listed under their topic, making
them easy to find and edit in Word.
Used reduced screen shots
Using the screen shots of the Advanced Job Cost windows with popup windows
proved to be a very effective way to provide help to the user. A major outcome
of this idea was the realization that perhaps our user manuals weren't explaining
the material in the best way possible. Also, perhaps online help would be
a better medium for giving the information the user really needed.
Conclusion
FrameMaker files can be converted to Word files suitable for use in RoboHelp
by several methods. With this version of FrameMaker, it is necessary to
remove all graphics from the document before converting. Another method,
which is less tedious, is to copy and paste sections. FrameMaker styles can
be removed from the Word file to reduce clutter. RoboHelp's WinHelp 2000
is a good option for getting the HTML Help look but still using the WinHelp
95 engine.
Using outlining in Word can be helpful in keeping your material organized,
provided all heading font styles are the same for topic titles. Developing
online help can give you insight on a better way to structure your information.
In the case of the help for this job costing application, screen shots with
popup windows of the various items proved an effective way to assist the
user.
1. Why should you study the relationship of the product and manual?
2. Why would you use WinHelp 2000?
3. Why would you use Word's outline feature?
If you got all three correct, you are on your way to becoming a Champion
in using FrameMaker. If you had problems, you had better look over the
material again.
What do you think?
Do you have any questions, comments, or opinions on this subject? If so,
send
an email with your feedback. We will try to get back to you as soon as
possible.
Feel free to establish a link from your website to pages in this site.
Students and researchers
The Web address of this page is www.school-for-champions.com/framemaker/fmtorobohelp.htm.
Please include it as a reference in your report, document, or thesis.
