Publishing WebHelp

Using RoboHelp

For a long time I used the wizard to publish my help as well as to generate it. The main points to note are some settings that can otherwise cause confusion.

One of the common complaints about the publishing wizard is the time it takes to upload to the server. You have to be fair to RoboHelp as it is either doing a partial audit of the whole project and uploading what is required or it is uploading the whole project. Both will take some time.

If you have just changed some topic text without amending the TOC, the index, browse sequences and so on, then that time can be frustrating. In that scenario you may prefer to use an FTP program to just upload the single file. Experienced users will know what to update. For others, if you regularly also publish to your hard disk without the Republish All option selected, then RoboHelp tells you what files it has updated to the local copy and you can then FTP those.

As I have indicated, RoboHelp does not delete from the server any files that are no longer required and I believe that is true of most HTML editors. So how can you manage that aspect? I recently encountered a problem with the wizard and the end result is that it is taking far longer than it did to publish anything. That forced me to consider what else would automatically update topics that had changed and did not require me to manually check what needed to be published. I found that a program I use for backing up my work had the answer. See the next section.

Using SyncBack

One of the common causes of problems with RoboHelp is authors running the project across a network. It causes all sorts of problems that have cropped up over the years on the forum and when authors are told of this, the usual response is along the lines that it is company policy that all work is saved to the network so that it gets backed up. Now it is clearly right that the work gets backed up but that argument cannot be used to enforce working off the network where doing so is going to corrupt a project. Patently that is nonsense and compromise has to be reached. What I have done is install SyncBack and every night my work is automatically backed up to the network. Easy and everyone happy.

That is the Back part of SyncBack. When I found RoboHelp was taking an inordinate amount of time to publish I needed to find another solution until I could locate the cause. For that I turned to the Sync part of SyncBack. That is designed to synchronise folders. The first pass will take a bit of time and effort to get right but after that updating is very simple and, importantly, the process will check for files that should be deleted from the server, a big step forward that ensures the site is tidy at all times.

The Process

First Time

Identify files that should not be on the server.

Create a SyncBack profile to synchronise the generated output with the published output on the server. At this stage we are only interested in files that exist on one side of the synchronisation. Until you have run the profile a few times, run it in Simulation mode so that no changes are made. There are a number of options in SyncBack to deal with the differences. Initially set them all to Prompt.

When you run the profile (simulated) you will get an on screen report. Where the file exists in both locations you will most likely see File Collision reported. At this stage, ignore that. What you are looking for is where SyncBack reports that the file is only on one side of the synchronisation. In most cases it will be files on the server that are not in the generated output. Unless they are there for valid reasons, delete them and keep running the profile until only File Collisions are reported or you can account for the differences.

At this point, the server has all the right files although the process has not checked they are the right versions.

Get a copy of the published files onto your hard disk

You need the file dates and times to be the same as on the server. One way of doing that is to create an empty folder on your hard disk, then create a SyncBack profile to synchronise that folder with the server. Set up your hard disk as the source and the server as the target with the options set to move any missing files from right (target) to left (source), which will of course be all of them.

This is the SyncBack profile you will be using to publish the output to the server in future so you need to change the settings of this profile how you want the synchronisation to run normally. In most cases you will want the source to overwrite the target.

After changing the settings, run the profile again in simulated mode. This should not find any differences. If it does you need to consider why as it should be a mirror of the server.

Normal Use

Generate and Publish the WebHelp

Generate to the usual location but publish to the folder you created on your hard disk, not to the server. Make sure that the Republish All option is not ticked as the whole process relies on identifying just the changed files.

Compare the generated and locally published help

This step ensures that unused files do not build up in your local copy of the published output. Remember that the generated help folder gets cleaned out every time you generate whereas the published folder does not. Also remember that it is what is in your locally published help folder that determines what is on your site.

Create a SyncBack profile that you will run in simulated mode only as you did at the beginning. We are just identifying files that only exist on one side of this synchronisation. There should never be files that are only in the generate folder but there may be files identified in the locally published help that are not in the generate folder. Use Windows Explorer to delete any files that should not be in the locally published help folder.

You do not have to do this every time you publish, just when you want the next stage to remove files no longer used.

Compare the locally published help with the server

It is this step that updates the server with new files and, importantly, can remove files that are no longer required on the server.

Run the SyncBack profile that compares the source (the publish folder on your hard disk) and target (the server). Do this in simulated mode at first if you prefer. However you may find it more efficient to run it in normal mode; SyncBack reports the changes it is going to make before it makes them and gives you the chance to change the action for each file or to abort.

Now for a very useful tip. Each time you run the profile, you get the chance to include / exclude folders. So exclude the folders that you know contain material that has not been changed, then SyncBack does not have to look at those. That minimises the time the process takes. I suggest however that you do a full synchronisation from time to time as an audit.

FTP

You can of course update your server by using FTP to transfer the topics to the server. That will be the quickest option and is fine if you have the expertise to know what needs to be updated.

If you prefer to use some other FTP client, then Rick Stone's July 2005 Not So Smart Publishing Wizard may help you.

What you don't get if you FTP is an audit.

Topic Revisions