Skip to content

Recent RoboColum(n)s

25
May

Which RoboHelp Server Report to use?

One of the major selling points of the RoboHelp Server application is its in-built reports. These give you quick and easy access to statistics relating to how often your users access the documentation, how they access it and their own PC environment. The statistics are displayed in both a graphical and list format to enable you to gather both summary and detailed information.

However when first using the reports, it can be difficult to choose the right report for the required purpose. This is due largely to the report names, a legacy of past RoboHelp Server releases. Whilst I know that Adobe is aware of this and looking to address it, I hope the following guide will help users until such time as they can deliver.

  • Help System Errors: Displays errors relating to the help documentation (e.g. missing projects, no default window definition, missing CSH identifier, etc.).
  • Usage Statistics: Provides details on how many “hits” the help documentation gets over a set time frame. The report can also be used to view the operating system and browser being used by your users.
  • Question Trends: Displays the number of searches performed by users that return no results (see the Unanswered Questions report).
  • Frequently Asked Questions: Displays statistics related to the most frequent searches used by users in the help.
  • Areas Requiring Help: Probably the least well named of the reports. It lists the most frequently accessed context sensitive help topics.
  • Unanswered Questions: Displays statistics relating to the searches performed by users that yielded no results.
  • Frequently Used Content: Displays statistics relating to the documentation topics that the users most visit.
Share SHARE
24
May

Are you a “Writer” or an “Author”?

Regular readers of this blog will know that I love the idiosyncrasies of language. The manner in which it has evolved makes it a rich and interesting communication resource. English, or any other language for that matter, is a mixture of words, terms and phrases stolen from other sources and adapted for local use. For example, how many of you know that the word “egg” is a Norse word that came over to England with the Viking invaders in the 8th century? I’m not sure about “Chicken” though! Or should that be “rooster”, “fowl” or “chook”?

The trouble with the evolution of language is that it occasionally evolves a bit too far. You can end up with multiple words that can be used for the same purpose but which have fundamentally the same definition. You can even end up with words that don’t have any meaning at all. Take the generic greeting, “Hello”. What does it mean? We all know when to use it, so much so that it is used in just about every modern European language and quite a few others beside. What does it mean? Where did it come from? No one is really able to tell us.

Worst of all for a technical communicator is where language sends you a curve ball. Sometimes you can use one of two or three different words to describe the same thing. Take the following examples:

  • “Writer” or “Author”
  • “Fog” or “Mist”
  • “Ship” or “Boat”

Dictionaries rarely help. I remember reading one definition of “Fog” once which read, “A heavy mist”! When does a mist become a fog? At what size does a boat become a ship? Or does is it about size at all? What about a Schooner? Is that a boat or a ship? Are the words “Writer” and “Author” interchangeable? I don’t know but perhaps I should get out more.

Share SHARE
13
May

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: Outputs a single .AIR file that is used to install the AIR Help application that contains the help output on the end user’s PC. Also allows users to add comments to the help. Viewed using its own browser.
  • Browser Based: Outputs an array of different files (similar to WebHelp) with an AIR theme and skin. Can be viewed in Internet Explorer, Firefox and Safari.

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:

  • Compressed: Outputs a single .JAR file.
  • Uncompressed: Outputs an array of different files.

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.

Share SHARE
5
May

I blame my parents!

Dang! I’ve just seen a job post advertising for a Technical Arthur. Personally I thought this sort of practice contravened equality laws. Just as well or else I’d never find the right position ;-)

Share SHARE
5
May

Microsoft Ribbon Hero or Villain?

When I took my first foray into technical writing, my boss used to often answer any questions I had relating to style, format or wording with “How does Microsoft do it?” I’ve always felt this was an easy answer to what can often be a complex question, but it does sometimes provide a solution. However as my career progressed I’ve learned to be more critical of what Microsoft and other companies offer by way of user assistance. Some companies have a lot of resource they can leverage and as a result produce multi-faceted, professional documentation suites. Microsoft is an example of this and as a result their tools and documentation are often held up as beacons of acceptability. The problem is that with acceptability comes expectation and the fact that you’ll never please all the people all of the time.

Never is this more true than the arrival of Ribbon Hero, a prototype game for Word, PowerPoint and Excel 2007 and 2010 users. Yes you read correctly. A game designed as part of Microsoft’s overall user assistance package. It is designed to help boost your Office knowledge by giving you challenges to complete (e.g. calculating the average value on a cell range in Excel). As you complete a challenge, you earn points that go towards your overall achievement score. Tips are available if you get stuck and challenges are categorised to enable you to focus on the challenges that are of most use to you. For example in Word they focus on:

  • Working with text
  • Page design and layout
  • Getting artistic

All well and good. The aim is that by performing tasks and adding a funky, game based element you’ll be more likely to remember what you have learnt. The points add a competitive element as you can share your score with other Facebook users, thereby earning greater bragging rights.

Always one to give things a try, I downloaded the game, installed it and gave it a try. The installation, as you’d expect from a Microsoft product, was a breeze. Once installed, the first time you launch Word, Excel or Powerpoint, the Ribbon Hero add-in is installed a new section is added to your Home ribbon. From there the game is accessible whenever you feel like playing.

On playing the game you are presented with a random challenge that you have to complete. The challenges range from the relatively simple (e.g. applying a style to a paragraph in Word) to ones that could well challenge all but the most experienced users. However the random nature of the challenges, plus their complete inability to allow you to use such things as keyboard shortcuts, made this a frustrating experience. I found myself quickly and easily completing a function only to be told I hadn’t completed it correctly. What is more, I couldn’t carry on until I had. After a couple of really annoying messages to that effect, I gave up.

Summary

It would be fair to say that my experience of Ribbon Hero was less than complimentary. Such a form of user assistance could well prove useful to a younger audience who had little or no experience of the product. However I also like it to allow (or at least give tips) for alternative methods of performing a function. If I had a pound for every time I found someone who was amazed to find out that using a keyboard shortcut was quicker and easier than clicking through a menu item structure, I’d be a very wealthy man. Training aids like Ribbon Hero do nothing to help my bank balance! Ribbon Hero was initially fun to use, and the concept of a game is interesting, but as time went on its point was lost on me. Whilst it does work on one level as a form of user assistance, it does not work for me. No doubt Microsoft will say I am not in the demographic that Ribbon Hero is targeted at, to which my response is , “Thank Christ for that.”

Share SHARE