nside Indexing with RoboHelp HTML by yaohongm


									                                                                                                                           by Suzanne Smith

          nside Indexing with RoboHelp HTML
RoboHelp HTML
RoboHelp HTML, from eHelp Corporation, is a powerful software tool for creating online Help systems. Included within RoboHelp
HTML is the ability to develop indexes for online Help projects.

As a technical writer at eHelp, I have been in the interesting position of creating indexes with RoboHTML while working directly with
the programmers who develop the product. This allows me to offer input (some of which is taken, some not!) and to fire off questions to
the experts who sit nearby. Following are some tips and tricks learned the hard way and by pestering the right people. Included are
ideas for all levels of RoboHelp HTML users, from green beginners to hot-shot pros.
Note: The tips and procedures that follow were developed using RoboHelp X3. If you are using an earlier version of RoboHelp, some of
this functionality may not be included or may require slightly different steps.

                                                      Topic keywords vs. index keywords
                                                      An important decision to make from the very beginning of your project, if
                                                      possible, is whether to use index keywords or topic keywords in your index. You
                                                      can use either type or both in a single index. Index keywords and topic keywords
                                                      display the same way in your final index, but they are stored differently. Any
                                                      index keywords in your project are stored in a separate file with the .HHK file
                                                      extension (e.g., myprojectname.HHK). Topic keywords are stored in the topic
                                                      properties of the topic to which the keyword has been added. There are pros and
                                                      cons to both types of keywords.

                                                      Note: How can you tell if an index entry is stored in the .HHK file or in a topic?
                                                      In RoboHelp X3, look at the keyword icons in the Index Designer. The icon for a
                                                      topic keyword is a key on top of a piece of paper . Index keywords have an
                                                      icon that is just a key .

                                                      Index keyword pros:

                                                         Can cross-reference index file keywords to other index file keywords
                                                         Can link to local HTML topics, bookmarks, and URLs
                                                         Can be sorted in any order (as long as you are not creating a binary index and there are
                                                         no topic keywords in the project)
                                                         Can merge index files with other projects

                                                      Index keyword cons:

                                                         if importing a topic into a project, must manually assign index keywords to the topic
                                                         removing an index file keyword from the index causes all topics that were assigned to the
                                                         keyword to no longer include the keyword
                                                         if you remove a topic from a project and you do not choose to remove its references,
                                                         index file keywords used by the topic are marked as unused in the index (unless they are
RoboHelp HTML X3 Index Designer (left side of
                                                         used with other topics)
RoboHelp HTML program with Index tab selected)
showing both index keywords and topic keywords           if merging HTML Help projects, all indexes must be binary, so keywords will be
                                                         automatically sorted and cannot be rearranged

                                                                                                                           Continued on next page

May 2003 page 6
RoboHelp HTML, continued

Topic keyword pros:                                                                                            Linking to Web addresses from index

                                                                                                               keywords is a fairly common practice, but
   if importing a topic into a project, all topic keywords are automatically added to the index

                                                                                                               few online Help systems go beyond just

   topic keywords from multiple .CHM files can be merged into a master project.

                                                                                                               creating a link to the company home page.

Topic keyword cons:

                                                                                                               Coordinate with your Web team to develop

   cannot be cross-referenced to other keywords in the index                                                   interesting links between your online Help

   automatically creates a binary index with keywords that are automatically sorted in alphabetical            and your corporate Web site. Does the Web

   order within the index (you cannot custom sort the order of keywords)                                       site contain a product updates page, an

   can only link to local HTML topics and not to bookmarks or URLs                                             online newsletter for users, an examples

   if adding index controls to topics, the index file (.HHK) for the control only displays index file          area, or user forums? All of these can be

                                                                                                               directly linked to keywords in the index,


   when removing a topic from the project, the keywords associated with it remain in the index in              giving users new opportunities to find the

   bold, indicating they are not linked to a topic (however, the keywords do not display in the index          information they need.

   until you re-link them to other topics)
                                                                                                            Display index keyword

   if a comma is used in the topic keyword, only information after the comma displays in the
                                                                                                            topics in a secondary

   compiled .CHM file index (must use a different character, such as a semicolon)


   currently, there is no way to convert topic keywords into .HHK file entries

At first glance it may seem that index keywords are the obvious choice, especially since                    You can have topics linked to keywords

the ability to create cross references and manually sort the index are critical elements of a               display in a secondary window instead of

quality index, but don’t discount topic keywords for certain situations. For example, if                    your main online Help window. This can

you must manage several projects and share topics between them, having keywords                             be useful in several situations. For

associated with topics can be a big time-saver because every time you import topics, the                    example, it can be difficult to manage

topic keywords travel along. This helps you create new indexes quickly and ensures                          context-sensitive Help topics in an index.
consistency of keywords across all projects.                                                            ○
                                                                                                            Some authors choose not to include them
                                                                                                            at all, but context-sensitive topics often

To set the type of keywords used in your project, follow these steps:

                                                                                                            contain specific, important information. If

1. From the File menu, select Project Settings.                                                             you do include them, you can distinguish

2. Click the General tab.                                                                                   any context-sensitive Help topics by

                                                                                                            displaying the topic in a separate second-
3. In Add New Keywords to, select Index File (HHK) for index file keywords or Topics for topic

                                                                                                            ary window.

   keywords. Any keywords you add will be the type specified.

                                                                                                            Follow these steps to display a keyword

Linking to destinations other than topics

                                                                                                            topic in a secondary window:

Online indexes offer linking possibilities that simply don’t exist in a printed index. If you               1. Set Microsoft HTML Help as your primary

are using index keywords in your RoboHelp index, you can link keywords directly to                             layout. In the Project Manager, double-click

Web addresses, email addresses, multimedia files, newsgroups, FTP sites, remote topics,

                                                                                                               on the Single Source Layouts folder. Right-

and even baggage files. Think creatively about how you can incorporate these types of

                                                                                                               click on Microsoft HTML Help and select

links in projects, but use them judiciously and where appropriate. For example:                                Set as primary layout.

   Have you or your marketing department created any demos, video tutorials, or presentations of            2. Create a secondary window with the

   your application in a multimedia format such as .SWF or .AVI? If so, import the multimedia file             appropriate size and attributes. In the

   into your project, add an index keyword with the name of the demo, and link the keyword directly            Project Manager, right-click on the

   to the file. When users click the keyword in the index, the demo displays and begins playing. This          Windows folder and select New Window.

   can add a new dimension of sound and motion to your online Help system and index.                        3. Turn off the Binary Index feature. From the

   If your technical support department ever needs to work directly with customer files to solve a             File menu, select Project Settings. Click on

   problem and you have an FTP site in place, you can link directly from an index keyword to the               the General tab and remove, if necessary, the

   FTP site. Create an appropriate index entry such as “Technical Support, send files” and link the            check mark next to Binary Index.

   keyword to an FTP address in the format, ftp://mycompany.com/upload/.

                                                                                                                                    Continued on next page

                                                                                                                                          May 2003 page 7
RoboHelp HTML, continued                                   4. In the Index Designer, right-click on the keyword that you would like to display in
                                                              the secondary window and select Properties.

                                                           5. Click on the Advanced tab and from the Window drop-down menu select the name
                                                              of the new secondary window you created in step 2.

                                                           RoboHelp contains tools that can help you manage your index. These tools
                                                           can keep you organized, improve the quality of your index, enable you to
                                                           work faster, and help you collaborate with others more efficiently.

                                                              Spell check: Ensuring that words are spelled correctly is a given in a good index and
                                                              it is easy to spell check your index in RoboHelp. Just open the Index Designer and
                                                              click F7.

                                                              HTML Help Studio: This tool can potentially save you hours of work and avoid
                                                              the problem of having to recreate a lost index. If you need an original index file
                                                              (.HHK) from a project, but only have the .CHM file, not the source files used to
                                                              create the .CHM, HTML Help Studio can retrieve the index for you. To open this
                                                              practical tool, click on the Tools tab and double-click on HTML Help Studio. From
RoboHelp HTML X3 Index Keyword Properties –                   the File menu, select Open and navigate to a .CHM file. The source files used to
Advanced tab. Use the tools available in RoboHelp to
                                                              create the .CHM file are listed on the left, including the .HHK file. Select the .HHK
manage your index
                                                              file and from the File menu, select Extract. Save the file to a convenient location.

                                                              Index Reports: You can generate several different types of valuable index reports.
                                                              (To reach the reports, from the Tools menu, select Reports – Index.) The Keywords
                                                              report shows a simple list of all the keywords in your index, including subkeywords.
                                                              The Keywords and Topic report lists keywords immediately followed by the topics
                                                                                                       assigned to them. The Topics and Keywords
                                                                                                       reports lists topics in alphabetical order
                                                                                                       followed by the keywords associated with

                                                                                                       Once a report is generated, you can view it,
                                                                                                       save it as a .RTF or .TXT file, print it, copy
                                                                                                       it, or email it. Printing a report or sending a
                                                                                                       report via email are excellent ways to
                                                                                                       distribute your index for review. Sharing
                                                                                                       reports with other writers can also help
                                                                                                       maintain consistency in keyword choice
                                                                                                       between different authors and different

                                                                                                       If you have a very large project with topics
                                                                                                       organized in subfolders, you can generate
                                                                                                       subfolder index reports to obtain more
                                                                                                       specific information. On the Index Report
                                                                                                       tab, click on the down arrow next to Folder
                                                                                                       and select a subfolder. The report only
                                                                                                       displays keyword and topic information
RoboHelp HTML X3 Reports screen with Index tab selected and Options dialog displayed                   about the topics contained within the
                                                                                                       selected subfolder.

                                                                                                                             Continued on next page

May 2003 page 8
RoboHelp HTML, continued

   Topic status: You can use RoboHelp as an organizational
   tool to track the status of your topics, including topic index
   status. From the Project Manager, right-click on a topic,
   select Properties, and then click on the Status tab. Once you
   have finished indexing a topic, select Index in the To Do list
   on the right side to “check it” off the list. (In Status on the
   left side, you can use the drop-down menu to select a status
   option for the entire topic.) If you track the status of all
   your topics, you can then use the Topic Properties report to
   obtain clear information about the status of your project as a
   whole. This can be useful if you manage a team of writers all
   working on the same project or if you need to provide status
   reports to managers.

Add keywords your way
Just like the old advertising slogan, “Have it your way,”               RoboHelp HTML X3 Topic Properties with Status tab selected

you can add keywords and subkeywords to the index in
RoboHelp your way. Try some of these methods:

   Use the Index Designer to add keywords and subkeywords. To
   display the Index Designer, click on the Index tab in the
   lower-left corner of the RoboHelp program. Once the Index
   Designer is open, type new keywords into the text box at the
   top and click Add.

   You can add keywords and subkeywords while working on a
   topic in the WYSIWYG Editor. Simply highlight a word or
   phrase, right-click on the highlighted text, and select Add
   Index Keyword.

   Add index keywords and subkeywords when you create a new
   topic. From the File menu, select New - Topic and type in a
   topic title. Then, click on the Index tab and either add new
   keywords or click Add Existing and select existing keywords
   you want to associate with the new topic.

   Allow the Smart Index Wizard to suggest possible keywords
   and subkeywords for your project. To open the wizard, click
   on the Tools menu and select Smart Index Wizard.

   Add keywords and subkeywords directly to topic properties.
   Open a topic in the WYSIWYG Editor, right-click anywhere
   inside the topic, and select Topic Properties.

                                                                     RoboHelp HTML X3 WYSIWYG Editor (right side of RoboHelp HTML
                                                                     program withWYSIWYG tab selected) with a word highlighted and right-
                                                                     click menu displayed

                                                                                                                           Continued on next page

                                                                                                                                May 2003 page 9
RoboHelp HTML, continued                                                   Click the Index tab. In Keywords, enter a new keyword or
                                                                           phrase and then click Add. To add a subkeyword, enter the parent
                                                                           keyword followed by a backslash \ and then enter the subkeyword.

                                                                           You can quickly create keywords based on topic titles. Open the
                                                                           Index Designer by clicking the Index tab in the lower-left corner.

                                                                           Open the Topic List by clicking the Topics tab in the lower-right
                                                                           corner. From the Topic List, select the topic that you want to
                                                                           add to your index. Drag and drop the topic into the upper pane of
                                                                           the Index Designer. A new keyword based on the topic title is
                                                                           added to the index (you can rename the keyword at any time if

                                                                        Use the Smart Index Wizard –
                                                                        RoboHelp’s Smart Index Wizard can be used to help you
                                                                        create an index, especially if you are in a bind and need an
RoboHelp HTML X3 Topic Properties dialog with the Index tab displayed   index fast. It cannot, however, replace a skilled human
                                                                        indexer. The Smart Index Wizard simply identifies words in a
                                                                        topic that could possibly be used as index keywords, but it
                                                                        cannot manage the subtleties of indexing such as under-
                                                                        standing words in context, developing synonyms, and
                                                                        creating cross references.

                                                                        To open the Smart Index Wizard, click on the Tools menu
                                                                        and select Smart Index Wizard. The first screen of the wizard
                                                                        displays, enabling you to select different options.

                                                                        Two particularly useful options on this screen are the
                                                                        “Always Ignore” and “Phrases” word list options.
                                                                        The Always Ignore list enables you to develop a list of
                                                                        “noise” words that the Smart Index Wizard should never
                                                                        identify as possible keywords. Obvious choices include
                                                                        words such as “the” or “and,” but other options may
                                                                        include words that are specific to your project such as
                                                                        acronyms (if you are using the spelled out version of the
                                                                        acronym as an index keyword) or mathematical/scientific

                                                                        The Phrases list contains phrases that the Smart Index
First screen of the RoboHelp HTML X3 Smart Index Wizard
                                                                        Wizard should always include when identifying possible
                                                                        index keywords. For example, if your company is named
                                                                        “ZYX Corporation” you should add that name to the
                                                                        Phrases list so the Smart Index Wizard views the two words
                                                                        as one phrase, instead of two separate words. Maintaining
                                                                        the Always Ignore and Phrases lists ensures that the Smart
                                                                        Index Wizard suggests high-quality words for your index.

                                                                                                                     Continued on next page

May 2003 page 10
RoboHelp HTML, continued

The Smart Index Wizard contains many settings
that enable you to choose how the wizard identi-
fies words. For example, using the custom search
settings option, you can specify that the wizard
exclude all verbs and adverbs as possible index

You also have complete control over how the
wizard adds words to the index. You can select the
option to add keywords automatically or require
that the Smart Index Wizard display all possible
index keywords so you can decide exactly which
words you want to add.

To be honest, I had never used the Smart Index
Wizard until recently when our company pur-
chased an existing product. We needed to re-brand
the product and release it within a short amount of
time. The product included an online Help system
(created in RoboHelp HTML, thankfully), but had
no index. My boss stated that the top priority was
to edit the topics, but I insisted on including an
index as well even though I had no time to create
one. I turned to the Smart Index Wizard and had an           RoboHelp HTML X3 Smart Index Wizard custom search settings options dialog
acceptable, if far from outstanding, index within a
few hours.

Experiment a little with the Smart Index Wizard. You
may find that it can suggest some new words you
didn’t think of for an existing index or that it can
help you create an index fast in an emergency.

Suzanne Smith is a senior technical writer at eHelp Corporation in San Diego, California. She has written and indexed online Help and manuals for a
variety of eHelp products including RoboHelp Office, RoboInfo, RoboDemo, RoboPDF, RoboScreenCapture, and RoboLinker. Suzanne is a member of
the American Society of Indexers and STC’s San Diego chapter. She received a Master’s degree in Rhetoric and Writing with a specialization in
Technical Communication from San Diego State University in 2001. Suzanne can be reached at her Web site, www.suzannesmith.com.

           ASI Indexing Conference
                         “Northern Entries”
                           June 19-21, 2003
                Vancouver, British Columbeia

                                                                                                                                 May 2003 page 11

To top