The RoboColum(n)

My team has been using RoboHelp 8 in anger now in a production environment for a few months and have been blown away with its ease of use and functionality rich interface. Like any new application there are issues, but on the most part they are not significant and most have a reasonable workaround. We just evaluated things in the round before deciding that we could live with them. We’ve not had to change our procedures significantly. The only workload involved changing our style sheet, template and snippet usage together with the updating the associated style guide. That said, we didn’t need to change our style sheets and template but did so to accommodate functionality that had been implemented since the RoboHelp version we had upgraded from (X5).

We employed a slightly conservative approach deciding to have a new style sheet for use in our projects. This was a decision brought about by the new functionality centred about list and table styles. Particularly the use of multi-level lists makes our life so much easier when documenting procedural topics. Whilst we could have kept just the one style sheet, we have taken the opportunity to slightly change some of the legacy styles. This in itself is not a reason for maintaining two style sheets but inline styles are. We still have instances where inline styles (don’t get me started on these!) are prevalent. Our plan is to apply the new style sheet to all new topics and also to legacy topics that need amending, and leave the old style sheet on all other topics. As time becomes available we can devote time to migrating fully over to the new style sheet and delete the old one.

Our template (we only use one) contains a header, footer and topic title. The only issue we faced with it was that the footer appeared in the topic preview but not in the output. Eventually we discovered that this was down to a particular set of circumstances that are probably quite unique to us. Our footer is essentially a line provided by a style and a table with four cells. Each of these cells contained a hyperlinked image. As soon as we moved the hyperlinked images out of the table, all was well. This was hardly a deal breaker once we knew the cause and found a solution.

The only other real change was educating our authors in the use of multi-level lists. This works a bit like MS Word style functionality but as none of my team is that conversant with this, it took a session together to see how this should be used. The major issue was related to both a lack of understanding of style sheets over inline styles and the fairly complex structure of indented bullets. However once they saw how it is supposed to work they went away happy!

As we upgraded from X5, functionality that arrived in later versions has also been employed. Variables and especially snippets have been greeted with wild abandon! We have variables set-up for all our product names and components (some of which have a very annoying habit of changing two days before a product version launch) and snippets are in wide use for standard heading styles (e.g. “See also…”, “How do I…”, etc.). Finally the ability to have multiple topics open has allowed us to employ a dummy topic (with the relevant conditional build tag to ensure it is never output) that contains all manna of frequently used content that variables and snippets cannot handle (e.g. formatted tables). We just cut and paste them into the relevant topic. Simple!

If you are considering upgrading to RoboHelp from any version, there are numerous resources available to guide you through the process. I  have blogged about them here.