Planning the folder structure

The starting point was to develop a rough idea of the folder structure that would suit the project. That requires thinking about the content that will be created. In this case the product range is mainly what the bank's staff will see. So the following was needed:

• An introductory topic to explain the information that would be presented. This should be the default topic in any project.
  
• Some topics explaining how to use Customer Care and some other fairly high-level topics, such as a regular News topic and a Product Summary.
  
• Some topics about the products themselves.
  

How best to organize these? A fairly classic approach is to have one folder for the default topic and those topics that cover using the help system itself, and other folders that reflect the content structure, which in this case is the product range. Customer Care is new, so not all the products need to be covered in the first release. At this stage Customer Care just covers various loans and mortgages. Mortgages are, of course, a type of loan, so it could be argued this product should also be included in the Loans folder. It was not because of another factor. Mortgages in the fictitious organization for whom this help is written are dealt with by a specialist group of staff. Putting "their" topics in a separate high-level folder was a simple way to remind the author that this area was special. Have a structure, but don't feel it has to be followed slavishly.

A walkthrough of the content

Now I will describe the structure and the content to highlight the new features, the new interface, and some good practices. For simplicity, I will describe the contents of each folder generally, referencing specific topics just as necessary.

About folder

This folder was created to hold a single topic not included in any output. It is just there to give a basic explanation of the sample project to anyone viewing it without reference to this article.

Customer Care folder

As explained earlier, this folder holds the default topic, and topics about using the help. It was also used for information that was higher level than the product itself, such as Customer Care News and the Bonus Plan.

Having said specific topics will only be referenced as necessary, in this folder the topics are a bit diverse by design, so it is necessary to explain each one!

Welcome_to_the_Bank.htm

This is the default topic, and it immediately shows the use of:

• Variables
• Multiple languages in the same file
• An embedded Captivate movie, the spinning globe.

The use of variables can be seen by looking at the source file. Experience Bank operates in a number of countries, but Customer Care was only required for use in the US and the UK. In the UK the bank operates under a different name, so a variable was used to change Experience Bank to Experience Bank UK where required. Using these two countries also meant that terminology becomes a factor. For example, what would probably be referred to as an Auto Loan in the US would be known as a Car Loan in the UK, another example of how variables can be used.

Four languages are used in addition to the main language of the topic and these surround a spinning globe that was added to create a little bit of a wow factor.

Using_Customer_Care.htm

This is a fairly standard topic explaining the icons used in the project. Note that the footer is the standard footer used in all topics except the default. It shows that a link can be created to a corporate intranet, although here it has been necessary to just link it back to the default topic.

Customer_Care_News.htm

When a user opens help, it displays the default topic. However, in any project there may be other topics where the project requires that these topics be displayed prominently. Seeing the regularly updated Customer Care News is an example. Clearly, only one topic can be made the default; but including Customer Care News in the top-level book of the table of contents reminds readers of it whenever they open the help.

Product_Summary.htm

This topic was included to show you the interior of a beautiful Mercedes-Benz motor car. Oops. No it wasn't. It is there as another example of a topic that Experience Bank wants its staff to see regularly. The car is there in honour of Alfred Hitchcock. (Older authors will understand.)

Bonus_Payment_Plan.htm

This topic was deliberately kept simple so that you can quickly see the code for a whole topic in a single window. See how much cleaner the code is than in earlier versions.

International Offices folder

The topics in this folder are simply targets for the links in the default topic. Many organizations will use a system such as this to publish contact details. They can either be in this form (a page per location), or they can be a listing.

Loans folder

The first product category that Experience Bank wanted to put into Customer Care was Loans. The four types are shown in Figure 3 in Project Manager, and inevitably, there are some elements of any type of loan that are common and some that are not. The two markets in which the system would be used, the US and the UK, also gave rise to differences such as loan limits being expressed in different currencies. These differences were addressed by the use of snippets and variables.

In real life, there would probably be subfolders for each loan type, each containing rather more topics. In this scaled-down sample project, that was not necessary.

After the sections describing snippets and variables, the new way of viewing the folders, topics and images is described under "Project Manager."

Figure 3. The four types of loans viewed in the Project Manager

Snippets

The layout chosen for the product topics in Customer Care has a "What's covered" table cell telling users what they will find in the topic. This is a common method, and it helps the reader quickly see if the topic is what they want and where to find specific bits of information. Hyperlinks take users to a particular section by using bookmarks. The process of writing the Auto Loans and Personal Loans topics identified some common areas. A quick review of the content of those common areas identified that the content could be a standard across all the loan products. The content was written in one topic and then created as a snippet by simply right-clicking and selecting Add To > Snippets and applying a name in the dialog box that is displayed (see Figure 4).

Figure 4. Adding a snippet

By repeating the process, a library of snippets was created (see Figure 5). There are various ways of using snippets, the simplest way is to simply drag the snippet to the point at which it is required in the topic.

Figure 5. The Snippets panel showing a snippet library

Now that you have added the snippets in the loan topics and added the content unique to each loan type, there remained the task of bookmarking the content so that the links can be created from "What's covered?" Snippets themselves are not designed to be bookmarked or contain bookmarks, so the first option seemed to be to place a bookmark at the end of the previous paragraph. But what if that was another snippet? Challenge: Often when creating topics, authors want to do something that is a bit different or wasn't built into whatever help authoring application they are using; the challenge is to find a good method. Fortunately, this one didn't take too much effort and just involved the clever use of a style in the CSS file. It simply involved creating this style:

P.SnippetBookmark {visibility: hidden;}

If you look at the loan topics in the WYSIWYG editor, you will see an extra line that would not be wanted in any output. However, preview those topics or create any of the outputs and that line cannot be seen, because, wait for it, it is hidden! It does, however, enable a bookmark to be created on that line so that "What's covered?" can link to both topic content and snippets.

There's more to snippets than this, and that is covered in a separate article. See "Where to go from here" at the end of this article.

Variables

The text for the loan products had to recognize that in the UK Experience Bank trades as Experience Bank UK, and any loan limits need to be expressed in £ (British pounds) rather than $ (US dollars). This was simply dealt with by using variables. The defaults are shown in Figure 6.

Figure 6. User defined variables representing the loan defaults

When creating an output, be it WebHelp, compiled HTML help or printed documentation, the wizard allows the author to accept the values shown above or to enter alternative values.

Project Manager

There's a new way of looking at your topics in RoboHelp 7, but the old way is also available if you prefer to stick with that.

In Figure 7, the traditional layout is shown with separate folders for topics and images and so on.

Figure 7. Traditional Project Manager layout

Now note the change when you click the highlighted icon (see Figure 8). Fewer folders appear at the top level.

Figure 8. New Project Manager layout with fewer folders

More importantly though, note the view under the expanded Loans folder shown in Figure 9.

Figure 9. Expanded Project Manager layout with the Loans folder showing its images

Previously only the topics would have been displayed, seeing the images in that folder required a trip to the Images folder, which wasn't really a folder and caused much confusion. Now all the files in the Loans folder are shown. Project Manager shows the same files as Windows Explorer with the exception of RoboHelp's internal .FPJ file. This is so much more intuitive: instantly, the author can see what resources are available in that folder.

Figure 10. The same folder seen in Windows Explorer.

Mortgage Specialist folder

The Mortgage Specialist folder was introduced purely as an aid to the author. The topics are about a specific type of loan and could easily be included in the Loans folder. The reason for putting them in a separate folder is that this effectively creates a reminder for the author that the content is for a specialized and limited audience. You can quickly see that a conditional tag is applied to all the topics. Seeing that reminds the author of the target audience and the need to ensure the content is written appropriately. Also, while a conditional tag can be applied to a folder, only the topics in the folder at the time the tag is applied are tagged. RoboHelp does not assume that the tag is also to apply to all future topics in the folder. In this scenario, that probably would be a requirement. Putting these topics in a separate folder enables the author to quickly spot any new untagged topics.

The Repayment Calculator topic was introduced just to show the sort of thing that can be introduced using Adobe Flash.

Media folder

This Media Folder was created in accordance with the author's normal working practice. It is simply a means used to help organize images, Adobe Captivate movies and suchlike.

• Where those files are used in just one topic, the author saves them to the same folder as the topic.
• Where they are shared across topics, then they are stored in the Media folder created by the author.

It's simple, tidy, and it works.

The outputs

RoboHelp 7 introduces various features that improve the ability to single–source; that is, to produce different outputs from the same source files. Snippets and variables have been covered earlier, but there's more:

• Multiple TOCs, indexes, and glossaries
• Search highlighting and breadcrumbs

Multiple TOCs, indexes, and glossaries

In previous versions, conditional build tags could be used to include or exclude books and topics, but that was about the limit of creating different TOCs without holding them in different files outside the project and swapping them over at shipping time! (Where there's a will, there's a way!)

Now they can be created properly within a project, enabling the use of a specific TOC for a specific output, as illustrated later in Figure 15.

Search highlighting and breadcrumbs

Search highlighting in WebHelp is a long awaited and welcome feature. The number of accesses to the page on Peter Grainge's site showing how this can be done using Calvin Ly's script in earlier versions of RoboHelp is testimony to that. Now it is simpler and built into RoboHelp. The author just chooses to include the feature in the output and sets the color for the highlighting. The reader has the option to turn it off as well.

Figure 11. The user can turn off search result highlighting.

There are many JavaScript methods for showing breadcrumbs, but not too many people seem to have implemented them successfully in RoboHelp. Now, in WebHelp outputs, it is as simple as ticking a field and setting the font and color of the breadcrumb text.

Figure 12. Breadcrumbs showing where the topic is in the TOC structure.

Using single source layouts

As well as describing how the new features come together in generating the outputs, this section also covers some information about making best use of some long available functionality in this area that many authors seem to miss.

Many authors look at the default layouts shown in Figure 13 and assume that's it.

Figure 13. Single source layouts in RoboHelp 7

It is thought that if two different WebHelp outputs are needed, the parameters have to be changed each time on the way through the wizard. The good news is that it isn't that difficult. Right-click any layout and menu in Figure 14 appears. Click New Layout, where the parameters will be very different, or click Duplicate Layout, where just a few details will change.

Figure 14. The Layout popup menu

The best way to see how creating new outputs simplifies the task is to look at the ones used in the Customer Care project. Open the About folder and topic. At the end of the topic, each layout is listed. Click the link and the details of each layout will be described. Creating a layout for each output required is so much simpler than remembering the different selections in each.

The author might, for example, have two layouts otherwise identical except for the TOC used. Rather than remembering to change the TOC selected each time an output is generated, it is more efficient to create two layouts with suitable names. They will be identical except for the TOC defined, but the risk of forgetting to change the TOC and issuing the wrong help is avoided.

Quick tour

The layout generation wizards have changed to accommodate the changes described in this article. The new screens are shown below, and that also illustrates how having multiple layouts avoids having to make changes.

The WebHelp Wizard page 1

In the first page of the wizard, shown in Figure 15, three areas will change with each layout. By having three WebHelp layouts, you don't have to make those selections each time you generate an output.

Figure 15. The WebHelp Wizard page 1

Clicking the Edit button for variables will display the screen in Figure 16 and again, the multiple layouts mean that the variables shown here can be used in this layout while another set of values can be created and stored for another layout. Always aim to minimize the changes needed at generation time as that is when the pressure is on and when mistakes are often made.

Figure 16. The Variables sub-dialog box from the WebHelp wizard page 1

The WebHelp Wizard page 2

This is where you can enable and define the new Search Highlighting and Breadcrumb features (see Figure 17).

Figure 17. The WebHelp Wizard page 2

The WebHelp Wizard page 3

If you use WebHelp on an intranet, changing the default to the Local PC setting can improve performance (see Figure 18).

Figure 18. The WebHelp Wizard page 3

The WebHelp Wizard page 4

In this instance, the WebHelp was not being published to a server, so nothing was set up in the last page of the wizard (see Figure 19).

Figure 19.

The other layouts described in the About topic should be examined to see just how useful multiple layouts can be.

Conclusion

Adobe RoboHelp 7 marks a new stage in the development of a favorite help authoring tool. The author hopes that, as well as describing some of the new features, this article has helped newer authors identify some good working practices.

Where to go from here

Download the latest version of the Customer Care project (English Language only).

Read the following articles:

• Read David Locke's article, Snippets in RoboHelp 7: A new way to work smarter.
  
• Read Craig Clarke's article, Leveraging the user-defined variables feature in RoboHelp 7.

Page 3 of 3

Previous Page