Where RoboHelp and RoboHelp Server users collide
As a user of RoboHelp Server in a team of five writers spread across three locations, we occasionally come across minor issues with its use. One of those is how we manage the publish process from our RoboHelp projects.
What is the best RoboHelp output format for me?
This is a fairly regular question asked on the RoboHelp user forums by those unfamiliar with the myriad of different output types available in RoboHelp. To make matters worse, it is often difficult to answer without knowing the Technical Writer’s specific requirements and those of their users. The issue here is that each output format is intended for use in a particular set of circumstances. Each format also has its own set of characteristics that until you understand makes answering the question of which output type to produce more difficult.
To help answer the question, the main output types and their characteristics are documented in the table below:
| Output Format | Purpose |
| Microsoft HTML Help | Designed to be installed on an end user’s PC (e.g. by an application’s .SETUP.EXE file). Following a Microsoft Security Patch you are unable to easily view the content when viewed on a networked drive. Outputs a single.CHM file. |
| WebHelp | Produces HTML output primarily designed to be installed on a website, server or intranet, although it can also be run locally on an end user’s PC. Outputs an array of different files, all of which must be published to the required location. |
| FlashHelp | Produces Flash output primarily designed to be installed on a website, server or intranet although can also be run locally on an end user’s PC. Outputs an array of different files, all of which must be published to the required location. |
| WebHelp Pro | Basically the same as WebHelp output, but used exclusively when publishing HTML output to the RoboHelp Server application. Outputs an array of different files, all of which must be published to the required location. |
| FlashHelp Pro | Basically the same as FlashHelp output, but used exclusively when publishing Flash output to the RoboHelp Server application. Outputs an array of different files, all of which must be published to the required location. |
| AIR Help | A relatively new output type designed for use across different platforms or browsers. AirHelp can be produced in two formats:
Locally Installed AIR Help has additional functionality over Browser Based AIR Help, although the gap is expected to thin out as the output type is developed in future RoboHelp releases. |
| Eclipse Help | This output type produces built in documentation into the Eclipse platform and accessible from the Help menu. Outputs an array of HTML files with an XML based Table of Contents. Requires a PLUGIN.XML file to display the help. For further details of how to produce Eclipse help from RoboHelp, click here. |
| ePub | An output format designed specifically for various eBook readers. It is an XML based output that in effect creates a digital version of a traditional printed book optimised for onscreen reading. This output type can be created via RoboHelp inbuilt scripting tool. |
| Kindle | OK. Kindle output can not be output directly from RoboHelp. However I’m reliably informed that the open source Calibre ebook management application can convert output from the ePub output type to display on a Kindle. |
| JavaHelp | A Java based output designed to be viewed in a JavaHelp Viewer. JavaHelp can be produced in two formats:
JavaHelp has some limitations compared to other output types. Click here for details. |
| Printed Documentation | Generates a Microsoft Word file from your RoboHelp project. From RoboHelp 8 it can also create a PDF. |
| WinHelp | Produced from the RoboHelp for Word application and designed to be installed on an end user’s PC. No longer widely used except in legacy help systems. The 32-bit Help file viewer required by Windows to view WinHelp files is not shipped with Windows Vista or after. However it can be downloaded by clicking here. |
| XML Output | Uses handlers to convert the project or topics into a DocBook or XML files. These handlers can be customised by using the HDF Editor. |
Note: This guide is designed as a summary of the main output types available. More detailed information on each can be founds by searching the web. One of the more useful sites is Peter Grainge’s site, particularly for WebHelp, AIR Help or JavaHelp.
A review of the Noughty’s – Part 1
David Farbey tweeted recently on how he had noticed how everyone had started summarising the years 2000 to 2009. As the end of a decade is such a momentous event (?) it is probably inevitable that editors struggling for a story during what is called “the silly season” turn to an easy fix. Not to be outdone, and honoring the fact that I have, officially at least, been a Technical Writer since 1999, I offer my own completely unscientific review of how the technical communication world has changed in the last ten years.
Note: I have split the review up into parts. Part One covers the migration from static offline help to user generated on line help.
Help….WinHelp!
In the good ol’ days when I had loads of money (pre-marriage) a full head of hair (also pre-marriage and pre-work) and technical communicators were easily pleased, I produced my first piece of documentation in WinHelp format. The sleek, familiar user interface made my first foray in technical writing a relative breeze. Oh how the mighty has fallen. One look at a WinHelp project these days makes me wince. OK there were some good things about it (e.g. non-scrolling regions) but on the whole it just doesn’t cut it in today’s feature rich, customer interaction environment. They just didn’t provide enough functionality for the discerning user and we Technical Writers just had to go. Whilst they are still used to this day, despite Microsoft’s best efforts, they are few and far between having largely been relegated to legacy help files for old and tired applications that have yet to be sunset or assigned a budget to upgrade.
The step to Microsoft HTML Help brought with it a rich stream of possibilities to improve user content. Like anything new it required a certain amount of getting used to, not least the fact that it was coded using HTML, but on the whole it was a huge step forward. Just the fact that you weren’t using MS Word as your editor was surely reason enough to change. However rather ironically a number of Help Authoring Tools surfaced that allowed you to generate the required HTML from a MS Word like interface. Now you could produce HTML in from a familiar interface without the vagaries of the familiar application! All of a sudden you could produce your HTML code without ever coding anything. Whilst it is possible to create your HTML topics in Notepad (I know someone who does even now) tools like Adobe RoboHelp provided an MS Word like user interface with which to produce your works of art. Microsoft HTML Help also brought with it a range of new gadgets and tools that allowed you to enrich your content (e.g. DHTML, browse sequences, forms, etc.).
However arguably even Microsoft HTML Help has its day. Whilst CHM files are still widely used and probably will be for sometime to come, the arrival of the Internet brought with it the need for online content. With the concept of a CHM being that they are designed to run on a local PC, we often used to see if we could bend the rules by placing them online. This worked to a degree but the incessant need for 100% security soon drove a dagger into any CHM file located online. They were deemed to be a risk and after Microsoft released Security Update 896358 in June 2005 they could no longer be effective unless located on a local drive.
Online help became the buzzword of the day. Outputs like WebHelp and FlashHelp gave Technical Writers the ability to change from being purely content providers to someone who could start to change the look and feel of the documentation we provided. The advent of skins allowed us to design the interface to the documentation as well as the documentation itself. What is more these outputs were more flexible allowing us to place them on internal intranets or an external site. Now our users could access the very latest documentation without having to install or upgrade an application. What is more, they could do so from anywhere provided they had an internet connection. All of a sudden staff in the field became enabled to find information quickly and easily.
Now I can’t let a review of output formats of the last ten years go by without mentioning my nemesis. For a short period after taking on my current position I was tasked with producing JavaHelp. The misguided decision made before I joined that this was the required output type because our application was written in Java was soon reversed! As soon as I pointed out the long list of its limitations and more importantly the negative feedback we were getting from users, particularly around searching, we managed to get agreement to change. If anything, it was this decision that highlights the changes that have occurred throughout my career. Namely that the documentation function has gone from something that costs, to something that can add real value to the product. The powers to be can see that it eases pressure points and can be a real difference to the overall user experience.
Viewing WebHelp Pro & FlashHelp Pro output in RoboHelp
One of the minor irritations of using WebHelp Pro or FlashHelp Pro outputs from a RoboHelp project used to be the workflow you had to run through to check the output as it appears on the server. Once you had published your output to the server, you had to open a browser and type in the URL of the Web Administrator. Only then could you logon and display the project.
All of this has changed with the arrival of RoboHelp 8. This version has a RoboHelp Server pod that can be displayed via the View > Pods menu item. When the pod is first displayed, a “Setup” button is displayed which when clicked allows you to enter the path and name of the RoboHelp Server. Once set, a “Connect Now” button allows you to view the project’s published output.
Tip:
It is a good idea to size the pod to a size that comfortably displays the Web Administrator dialog and save your environment via the File > Environment > Save Environment menu item. If you don’t do this, you’ll have to manually resize the pod each time it is opened.
A default Single Source Layout. What’s the point?
If you have only ever created a new project and specified the output format in the process, this is a question you may never have asked. However if you’ve had to change the output layout being produced from your project (e.g. for Microsoft HTML Help to WebHelp) or you output two or more different layouts, you will almost definitely have had to address this. On the face of it, your default single source layout allows you generate your chosen output by clicking a single toolbar icon. This is all very handy if you don’t have the Single Source Layouts pod displayed at the time, but it is so much more than that. It also controls your project windows, the table of contents properties and other project entities.
Take start with a look at your humble window. Isn’t it just a container in which you display your help? Unfortunately it isn’t quite as simple as that. The default single source layout at the time the window was created determines what window characteristics can be changed. The reason for this is that web based output (e.g. WebHelp) uses a browser to display the help contents. With a CHM file you have much more control over the window used to display the help because it is a single compiled locally installed file. As well as this, the window properties available differ. Web or flash based output requires a skin to control much of the look and feel of your output so the window definition needs minimal supervision. For example the skin controls colors, buttons, fonts, etc., whilst the window controls placement, default tab and properties when viewed from a context sensitive help API. With Microsoft HTML Help (.CHM) output it is the window that controls the buttons that are displayed as well as the look of the tri-pane container.
As for your Table of Contents, the default single source layout controls the properties of your books and pages. If Microsoft HTML Help is your default layout you can assign different book and page icons in the Advanced tab via the “Image” field. This is not available with other layouts. Likewise What’s This help can be added to the list of things not available to users with their default single source layout set to anything other than Microsoft HTML Help.
Hopefully now you understand that your default single source layout controls so much more than the default output produced. So if you ever face a situation where you can’t change the properties of your Table of Contents, window or other project entity, check your default single source layout setting. Changing your default is as easy as right clicking on the single source layout (in the Single Source Layout pod in RoboHelp 7 or later) and clicking “Set as Primary Layout”.
Note:
If you are publishing WebHelp Pro or FlashHelp Pro output, the default single source layout also controls the use of the RoboHelp Server pod (available in RoboHelp 8). If the default single source layout is anything other than WebHelp Pro or FlashHelp Pro, the Setup button in this pod will not be available for use.
