Category Archives: RoboHelp
RoboHelp for beginners
In recent days I have had to prepare for the arrival of a new Technical Writer. We recruited another post due to one of our number taking part time working and the pressing need to rewrite the help files for our major product. Together we will be working on the project for the next six months and we have to ensure that the new help files also include documentation for the new and changed functionality in a scheduled release. The new Technical Writer is straight from university and has never held a full time position. She has a lot to learn in a short space of time. There is using RoboHelp for a start and then there is the application that she and I will be rewriting the help for.
Having met her at her interview I have no doubt she will fit into the team well and is eager to learn. Good job, as when I sat down to plan her training, it hit me just how much there is to learn. It struck me as I looked at RoboHelp just how complicated the product can appear to some yet, at the same time, how familiar it can be if you look closely enough. Things are complicated a little by the fact that we are still using RoboHelp X5. Our new starter was proactive enough to have downloaded the RoboHelp 8 trial so had some idea of what to expect only to find that things look different.
I planned three sessions covering the basics of RoboHelp and the other applications we use, but what to cover in each one? I don’t want to go into too much detail at this stage, yet I want her to be comfortable in creating a project, adding topics, adding content and generating the output. This would allow her to practice herself with an exercise we have given her.
Planning training is a good experience for any Technical Writer as it highlights one of the major skills of the job; focusing on what exactly a user needs to perform a task. As a result I constantly had to ask the question, “What will she need to know to perform her job in these first few days.” As a start, a whistle stop tour of the user interface skimming over things like baggage files, links and the generated HTML. The premise being that under normal circumstances, and definitely in these early days of her career, she will never go near them.
As I planned the training it made me realise once again what an excellent tool RoboHelp is for a beginner. With the editing interface being similar to MS Word, the click and drag functionality throughout the product and the ease by which elements like the table of contents and index can be created, RoboHelp really is a joy to behold for any newcomer. OK there are other similar tools around but they are hard pressed to have someone up and running inside an hour.
The greatest baggage search story ever told!
In the dawn of time, before the great God of help authoring tools created RoboHelp, the world was a barren and unfulfillling place. Documentation professionals, especially those who maintained content for two or more audiences, worked feverishly at their keyboards with an unhappy listlessness. They held a forlorn hope that one day a tool would be created that would make the world a more pleasant and enriched place.
One day the prophet Macromedia (or was it e-help or Blue Sky) brought forth a version of RoboHelp with something called conditional build tags built in. These miracles of technology could be attached to topics or topic content and then used to exclude, or include, said content in the output. All you needed was an expression in the single source layout. Technical Writers saw that this was good and doth spoke with one voice, “This is truly manna from Heaven. Now we can maintain different content for all races from one set of source. It’s as easy as falling off yonder log.”
Indeed the world was a better place, but only for a short while. You see we Technical Writers got greedy. Not satisfied with the current functionality handed down to us, we wanted more. “MORE?” screamed the almighty Macromedia (or was it e-help or Blue Sky). “Does thou not knowest how difficult it will be?” A collective sigh could be heard from the heavens as we demanded the ability to add conditional build tags to Table of Contents pages. “Oh and whilst you are at it, what about other stuff as well?”
Just then, the clouds darkened and a crack of thunder rained down from the firmament. When the rain stopped, Adobe had bought Macromedia and a new RoboHelp version was forthcoming. Lo and behold it had implemented what we had asked for. We looked at it and sayeth, “Thank you, oh Omnipotent one. Now this tool can truly be called the King of HATs.”
And indeed it was. It even waxed lyrical whilst slaying those pretenders down the road at Madcap. Whilst rendering such sinners to an existence of functionality catch up, Adobe released yet another version (8) of the great tool RoboHelp. This one was THE one. It was a major redesign from the ground up and answered most of the questions unbelievers asked of it. It even allowed baggage file contents to be searchable, a feature previously only available to users of the RoboHelp Server.
But there was restlessness among the great unwashed, some of whom didn’t want their PDF content included in their user’s search results. “How could the great mighty one have allowed this to happen?”, they asked. But a savior was at hand in the shape of a little known file called SALIdxSvc12.xml. Lying unloved in RoboHelp’s install directory, this XML file suddenly found favor amongst those in trouble. It contains a list of file types that can be excluded from search results. So the miracle of the SALIdxSvc12.xml file was to remove the required <Type Ext=”.XXX”/> line(where XXX is the file extension of the file type to be excluded).
Lo and behold, we rejoiced and made merry. We just had to ensure that we restarted RoboHelp before creating our output and restoring the original file before working on any project that did require PDF content to be searchable. But beware as the small print has a warning attached. Do not try to add file types to the SALIdxSvc12.xml file that were not originally there. Such behavior will surely result in great floods and fires that will render your source code untouchable. You have been warned!
Update
Editing the SALIdxSvc12.xml file to exclude certain file types could also dramatically reduce your compile duration. It has been reported on the RoboHelp forums how a project of 330 topics and 2000 PDF files was taking seven hours to compile. After the SALIdxSvc12.xml file was edited, it took ten minutes!
Search and ye shall find…….maybe!
Questions occasionally crop up on the RoboHelp forums related to how the search works. They tend to come from the angle of what is used to build the list of keywords that are included in the search, and which users can search on. What they seldom focus on is what they do not search on.
RoboHelp’s search is based on a simple index of keywords made up of all the words in your help. In other words, each and every word you type is searchable in the final help file. Except that you can compile a list of words NOT to include in that index. This list, called a Stop List, is generally used for small words (e.g. “a”, “the”, “at, “and”, “to”, “1”, “2”, etc.) that you do not want to clutter the search results. These “noise” words are ignored when the help is generated so are not included in the list of searchable keywords.
Each RoboHelp project has a default Stop List from which you can add, change or remove words. The Stop List words are contained in the projectname.stp file to be found in the root directory of the project. If you have a stop list that you need to copy between projects, just copy and paste this file as required.
To change the contents of the Stop List you need to go into your Project Settings (e.g. File > Project Settings). From there click on the Advanced button to display the Localisation dialog. This dialog opens with the Stop List tab conveniently displayed and with three buttons down the side:
- Click Edit to change a selected noise word.
- Click New to add an additional noise word.
- Click Delete to remove a selected noise word.
Once all changes have been applied, click OK to save your changes to the Stop File and to exit the Project Settings. You are now free to generate the help in the knowledge that the searchable output will contain none of your chosen words.
Output files and so(u)rcery
The difference between a RoboHelp project’s source and output files can be an area of much confusion. This is especially true where users are more used to WinHelp, compiled HTML (CHM) or compressed JavaHelp output. With these output types you have one or two output files to worry about. Web based output however, has many more. Whilst it may seem unnecessary to understand the difference between the output and source files, it is essential in certain instances.
Take the scenario where you are faced with making changes to a legacy project that you have no knowledge of. You have the output but you don’t have the source. It is a common misconception that to recreate a project you just need to import the output files and, hey presto, off you go. Nothing could be further from the truth. In such instances it is always best to explore all avenues to find the source files. Or how about the scenario where you have a WebHelp project that is published to a test area, but which needs to be copied to a company intranet of SharePoint site once testing is complete. You could just republish to another location or manually copy the files, but which files should be copied?
Web based output types (WebHelp, WebHelp Pro, FlashHelp or FlashHelp Pro) output a series of files in a folder structure that largely mirrors the project’s folder structure. However there are some anomalies. For a start you may notice some additional folders. These contain versions of the output uses in different circumstances. The “whdata” folder contains DHTML files used by some older browsers. The “whxdata” folder contains output used in Java applet and DHTML versions on newer browsers. The “whgdata” folder contains pure HTML.
There are also other files likely to unfamiliar to those who haven’t seen them before. These include files related to context sensitive help, framesets, skins, style sheets and all manner of JavaScript files required by various elements of the help. These files are too numerous to list here but are well documented in the RoboHelp help file.
Users with access to web based output files often find there is no .XPJ file with which to open the project. This is a sign that you haven’t got the source. Some even try creating a new project and import the .HTM files they find in the output. If you do this, you are asking for trouble as the .HTM output produced by RoboHelp contains additional code which when imported back into a project causes it to complain loudly. Try creating a new project and importing a few WebHelp output files to see what I mean.
Compiled HTML output, as the description implies, compiles a set of HTML source files into a single deliverable file (.CHM). The file contains all that is required to display and use the file content and as such is, to this day, a natural choice for applications being installed locally on a client PC. Creating a new help file from a CHM however is relatively straightforward. RoboHelp has its own tool called HTML Help Studio that decompiles a CHM file into its constituent parts allowing you to create a new project from them. Just create a directory, select a CHM and point it at the directory and before you know it you have everything you need to proceed.
Before Compiled HTML output there was WinHelp. This uses Microsoft Word as the editor to produce a series of .RTF files from which a .HLP and a .CNT file are generated. The .HLP file is the package for the help and contains the tri-pane view and the topic area. The .CNT file contains the Table of Contents data and must be shipped with the .HLP file and installed in the same directory for the Table of Contents to be displayed. This output type is no longer widely used and cannot be used on Windows Vista or Windows Server 2008 PCs without downloading and installing the WinHlp32.exe, as it is not part of these Windows installs.
JavaHelp comes in two formats; uncompressed and compressed. Uncompressed JavaHelp produced a series of files in a folder structure in a similar fashion to WebHelp or FlashHelp output. Compressed JavaHelp outputs a single .JAR file. This is a bit like a compressed WinZip file and can be displayed in a JavaHelp viewer. As it is a single file, it is the favored method of delivery.
Making new fonts available to RoboHelp
The font used to display written or online documentation is the subject of a lot of rather heated debate. A good friend of mine would go into near apoplexy over the use of the Verdana font and how it rendered certain characters. Only Arial was good enough for him. Whilst the choice of fonts to use is certainly important, it is rarely something we pay attention to once the choice has been made. You can see why, as your Style Guide stipulates the style (and therefore fonts) to use in any given situation.
But what if you find yourself in a position where you need to document in a new font. Most of us would simply turn to the list of installed fonts and away we’d go. But what if the required font is one that we don’t have installed? We have downloaded the font from the web but how can we make it available to the application?
Each RoboHelp project has a RHFONTSET.APJ file in it’s root directory that contains the sets of fonts that are available to it. Therefore if a font doesn’t exist inside it, it can’t be used when editing a topic. But here’s the crunch. The file is created when the project is created. Therefore if you install new fonts after a project has been created, the RHFONTSET.APJ file knows nothing about them and they are unavailable for use.
To make these fonts available for use, you have two options:
- Create a new project which creates the RHFONTSET.APJ file with the updated font details. Now you can copy this file into your existing project replacing the old one.
- Amend the RHFONTSET.APJ file in a text editor. If you have the fonts in another file you can copy and paste everything between the <fontset> and </fontset> tags for the required fonts. If you don’t you’ll have to add the tags as shown below. Beware that there may have to be multiple entries in the file for italic and bolded versions of the font.
<fontset>
<name>xxxxxx</name>
<fontlist>yyyyyy</fontlist>
</fontset>
where:
-
xxxxxx is the actual font name (e.g. Arial).
-
yyyyyy is the text appears in the font drop down list.
