A topic that has come up on more than one occasion of late has been, what do I do once I have the RoboHelp Server up and running. In other words, you have the server software installed, with all the elements communicating with each other, and you have your RoboHelp project all finished and waiting to be published. Now what?
The answer is areas. Areas are a new feature of RoboHelp Server in version 8. I have covered these in another post so I won’t repeat myself here. In order to publish your output you’ll need to have at least one area set-up on the server. There is a default area called “General” but in my opinion it is better to create your own. So how do you create one?
If you have access to the RH Server Web Administrator (see below) you’ll see a series of icons on the left. The top icon is used to create the users who will have access to the various areas. They are grouped. So the process is:
- Click Add next to the “Select a Group” field in the Users panel.
- Specify your group name (e.g. Department A) and click OK.
- Select your group in the “Select a Group” drop down.
- Enter a new user name in the “Add new User“ field and click Add.
- Click Yes in the resulting dialog and complete the username / password fields as required and click OK.
- Repeat steps 3 to 5 for other users.
- Click on the Areas icon (second one down).
- Click Add next to the “Select an Area” field.
- Specify an area name ensuring the “Protected” option is enabled.
- Next you need to add the group you specified in step 2 by clicking Add next to the “Add new Group” field.
That’s about it and you’ll find that area is available to specify in the WebHelp Pro single source layout properties in the RoboHelp client. You just specify the area and publish. Once published, the project is displayed in the Projects panel on the RH Server Web Administrator.
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 centerd 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.
A documentation release, Microsoft style! Click here to see how to do it but don’t forget your sick bag.
I have just taken delivery of a new mobile (cell) phone. As is normal for me when I get any new toy I can’t wait to turn the thing on and play. Will I be reading the documentation? No! Not unless I have to Having said that, if I did, it wouldn’t take me long. The phone came with a getting started guide that amounted to a few pictures and a small manual of about 12 pages half of which is health and safety information.
It seems like if you want in depth information you have to look elsewhere. I did find a documentation directory buried deep down in the directory structure of the accompanying software CD. In there was a “full” user guide. I use inverted commas around “full” because it said correctly that you could synchronise data between PC and phone but nowhere told you how. It told you there was a wealth of applications and add-ons that could be downloaded without telling you where to look.
This sort of documentation is I’m afraid becoming more and more typical and the world is a darker place for it ;-(
Having implemented a RoboHelp Server 8 solution for the help files for one of our products, I am delighted to report that things have gone swimmingly. The installation of the server software went like a breeze, especially as both the server administrator and myself had no previous knowledge of Tomcat, and the publication of the help file output was as easy as falling off the log. Like anything new, there were teething problems and this post is about one of them. Take the image displayed below. Notice anything odd about it? Here’s a clue Look carefully at the Table of Contents.
In the Table of Contents the “Basic Tasks” book is clicked but the topic displayed is “Managing Tabs” which just happens to be located immediately above the selected book. This problem is limited to WebHelp Pro output when viewed on the server either by clicking on the “View Project” button in the Web Administrator or displayed via the application. It does not occur if you manually open the start page in a web browser from the RH server. Neither does the problem manifest itself using WebHelp output. Apparently FlashHelp Pro output is not affected although I haven’t tested this.
Annoying? Yes, but there are workarounds. The bug is limited to books that do not have a topic linked to it in the book’s properties, so linking all books in your TOC to a topic is an easy way around it. This raises the following issues:
- It would be sensible to link each book to the first topic in the book so as not to confuse the user. In the above example, the “Getting Started” book would be linked to the “Logging onto the Application” topic, the“Basic Tasks” book would be linked to the “Finding and Opening an Experiment” topic, etc. However if a topic is ever added to a book in the first position you would have to remember to change the book’s properties to change the link.
- Some have got around this issue by adding an overview topic to each book. As such the overview topic will always be the first topic and so the book’s properties will never require changing. The drawback here is that the overview topic may be little more than a sentence followed by a bulleted list of hyperlinks to other topics. This may not fit in with your style guide or vision of a useful help system.
- A third way around the problem is via the use of a redirect topic. The theory behind redirect topics is described in Rick Stones Tips n Tricks file, but basically it does exactly as it says on the tin. A topic is opened and redirects you to another topic. This would work in a similar way to lining a topic to the book’s properties but has the advantage that the topic is not linked to a book AND displayed in the Table of Contents. It is generally accepted not to be good practice to have a topic in the Table of Contents twice. Whilst the effects of doing so are mitigated by having the two Table of Content references beside each other I would still ere on the side of caution. The problem with redirects is that it requires the user to be comfortable with editing the topic HTML. This is not something to be considered likely as getting things wrong can cause untold problems. However if you are comfortable with this approach, this is my preferred option.
In summary, this bug is annoying and fairly difficult to track down. However it is not the end of the world. Hopefully this article has explained the problem so you don’t have to go looking for it, and proposes a number of solutions to alleviate it. As an aside, anyone affected by this is encouraged to report this to Adobe.