Explanation of how to create online help using Blue Sky RoboHelp from a user manual written in Adobe FrameMaker. Key words: technical documentation, communication, Microsoft Word, Windows Help, STC, Society of Technical Communication, Ron Kurtus, School for Champions. Copyright © Restrictions
Converting FrameMaker User Manual to Online Help in RoboHelp
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.
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.
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.
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.
Resources and references
Adobe Software - company that sells FrameMaker
What do you think?
Do you have any questions, comments, or opinions on this subject? If so, send an email with your feedback. I 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.
Click on a button to send an email, Facebook message, Tweet, or other message to share the link for this page:
Students and researchers
The Web address of this page is:
Please include it as a link on your website or as a reference in your report, document, or thesis.
Where are you now?
Converting FrameMaker User Manual to Online Help in RoboHelp