Using Contribute

What's covered?

This topic follows the general topic on Reviewing Help and describes how to use Macromedia's Contribute product with RoboHelp.

Contribute allows subject experts and others to edit your topics in much the same way as if they were using Word or similar, using Contribute to edit is straightforward. You can control the level to which subject experts can make changes and they do not need the level of knowledge required to use RoboHelp, also the licence costs a lot less! The only real hitch I found was the subject experts cannot see dropdown or expanding text, that may or may not be a problem for you.

My thanks to Arne Kvadsheim for posting the idea of using Contribute and his help in getting me started with it.

I have only tested this so far with webhelp but it should work where you are going to compile .CHM help.

The first thought that went through my mind when I saw Arne's suggestion was that the editing needs to be done on the source files.

If the output is webhelp, the output files are very different to the source files so you could not use any changes made to them.
If the output is a compiled CHM file, then the source file is the only one that could be edited.

Arne confirmed that was the case and advised that he makes the source files available. My thinking was that I was not happy allowing others in the company to work directly on the source files, too many risks. However, a copy can be created so I felt it was worth exploring the use of Contribute further.

Arne's site has an excellent topic on using Contribute generally and I strongly recommend that you also read that. What I have done here with Arne's knowledge and approval is describe the process specifically for use with RoboHelp.

You should also read the Contribute documentation which expands greatly on how the product can be used and the security features.

The Steps

These are the steps you need to use Contribute in conjunction with RoboHelp.

If you want to print this topic with all the dropdowns included, click the Show All button and then print.

You can also download a PDF version. Click here.

Step 1 - Copy the project where others can accesss it.

Step 1 - Copy the Project

This step needs to be done before you can do anything in Contribute. Simply use Windows Explorer or an FTP client to put a copy of your project somewhere that you and others can access it.

You also need to change the way the style sheet(s) for your project are referenced. RoboHelp will write the reference in your project something like this:

When you generate webhelp, that gets amended to

Note that the backslashes have become forward slashes.

You need to make that change to the copy using a multi file find and replace tool. Your search needs to include the quote marks surrounding the path. I have highlighted the search and replace strings in red. You can use the RoboHelp tool or something like FAR.

Reversing this change is covered in Step 5.

Step 2 - Create your connection.

Step 2 - Create Your Connection to the Project

Your role as author is the role that Arne describes as the Online Help Manager. You need to be able to access the copy project in the same way as those who will be reviewing the help, albeit that you and they will have different rights.

The opening screen in Contribute looks like this.

To create your connection click Edit | My connections | Create... to invoke the Connection Wizard.
Click the Next button to display the Website Home Page screen and enter the path to your project's default topic. It is important this topic is in the root. Note that you need the path and filename.
Click the Next button to display the Connection Information screen and complete the details. Make sure you use server names rather than drive letters as these will likely not be the same for all users.
Click the Next button to display the User Information screen and complete the details.
Click the Next button to display the Role Information screen.
Click the Next button to display the Summary screen.
Click Done.

Step 3 - Administration. Define who can do what and send keys to users.

Step 3 - Administration

After clicking Done in the previous section, you will see the My Connections window. From here you can define who can do what.

Click the Administer button to set up the required options.
Select the Dreamweaver-style editing option and then click the Yes button.
The dialog for the website details will be shown. The options shown on the left are outside the scope of this topic. The buttons on the right are covered below.

Edit Role Settings

Each Role can have different settings and by default those settings will apply to each user within that role.

You need to work through each of the options on the left in the screenshot below for EACH role.

General

I have decided that only I will be able to publish, Allow Users To Publish Files will not be selected for Writers. That way, all changes have to be submitted to me for review.

Folder / File Access

When looking at the reviewers changes, I want to be able to delete files but I will not be setting that option for the reviewers. I want them to delete the content and enter something like "This page to be deleted". That enables me to check the impact on the project of deleting a file.

Editing

Option	Comment
General Editing Restrictions	For all groups I decided to allow the options shown rather than being too restrictive. Depending on who will be editing your topics, you may wish to reduce the functionality for Writers.
Paragraph Spacing	Make sure this is set to Two Lines so that the settings for the <p> in your style sheet are followed. I found that I got odd results with any other setting.
Other Editing Options	I think the settings here are fairly self explanatory. I cleared the "Allow multiple consecutive spaces" check box for others as I know that will be abused instead of using styles and tables. I have left it in for myself as I know when it is safe to use.

Styles and Fonts

The Style Support dropdown options are a bit misleading. One of them is "Don't allow users to create styles." I interpreted that as meaning they could not create new styles as in styles I had not created. In fact it means that if they create new paragraphs, they cannot apply a style to it. My selection for all users is as above.

New Pages

This page allows you to restrict the ability of reviewers to add new pages.

Removing the option does not entirely prevent the reviewer from creating new pages using Contribute. They can separately use Contribute as an HTML editor. What it does do is prevent them from saving new pages within the copy project.

File Placement

The settings here only apply to any new files created. I decided that I wanted them all in the same folder so that when I get back to editing in RoboHelp, I can locate these items easily and move them there, if necessary.

Shared Assets

Not applicable to me so you're on your own!

New Images

You may wish to change the default settings here.

Don't forget, you need to define these settings for EACH role.

Create New Role

The default roles are as below:

Role	Description
Administrator	This is the online help manager's role (you) and you may decide to allow more editing capabilities.
Publisher	This role is much like that of a Writer but would also allow the user to publish the changes to the copy project. The original text is then lost and will not be seen by any subsequent reviewers. That is not something I want so I will not be using this role.
Writer	This is the role that will be used by most reviewers. You can rename it to suit your needs.

For me, those roles are adequate for my needs but you can create new roles with different options to suit your needs.

Send Connection Key

After clicking the Send Connection Key button, the Connection Key Wizard Welcome screen will be displayed.

Make your choice and click the Next button. These instructions assume you have selected No which displays the additional Connection Information screen.

Your connection details set up earlier will be shown as the default. Change the details as to how the reviewer will access the copy project and click the Next button.

Highlight the required role and click the Next button. Care, note that the order of the roles is not the same as in the Administration screen.

Your options here are self explanatory. Click the Next button when completed.

Click Done if you are happy with the settings.

Contribute will then display an email for completion. Complete the email and send it.

Step 4 - User creates their connection.

Step 4 - User Creates their Connection

To create their connection the user simply double clicks the connection key that you sent and enters the password you have defined for them. Contribute will open ready for review.

Step 5 - Reviewing. How reviewers use Contribute.

Step 5 - Reviewing

You now have your first reviewer set up ready to edit. After they have double clicked the key and entered the password, Contribute will display the home page that you have defined. The New Page icon will be disabled for reviewers.

To start editing, the reviewer simply clicks Edit Page and the page will redisplay with the toolbar shown below.

The reviewers options are limited to this toolbar and the menu.
The publish button will be disabled for them.
They will not be able to format the borders of tables created in RoboHelp so you will need to do that later but hopefully that will not be necessary. They can insert new rows and columns and edit text.
They can create new tables and format those. (I have yet to test those in RoboHelp.)
At the end of the session the reviewer can either Save for Later which allows them to continue at a later stage or they can Send for Review. This will invoke an email to you stating the page has been edited and notes can be added to help you.

If you now open Contribute this message will be displayed
The pages ready for review will be listed on the left and you simply go through accepting, rejecting or changing as necessary. When you have finished, click the Publish button and the file will be changed in the copy project.
As you work, make a note of all the files that are changed.

Step 6 - Update the original project.

Step 6 - Updating the Original Project

There are two main ways that you can tackle this.

Clean up the copy project that the reviewers have been working on.
Import the topics from the copy project back into the original.

Clean up the copy project

Contribute adds various files whilst the reviewers are working on the project. These are all stored in folders prefixed with an underscore and typically _mm. It also creates a _notes folder.

I suggest you take a copy of this copy project until the process is complete. You can delete all the folders with the underscore prefix. This gives you a complete RoboHelp project from which you can now compile or generate your help.

Remember that the path to your style sheets now has forward slashes instead of backslashes but this will not affect webhelp. If you are compiling .CHM help, I have not yet tested to see whether you need to restore the topics to using backslashes.

Import the topics back into the original

Until you are entirely comfortable with this process, I suggest you take a further copy of the original and save it somewhere safe.

Condition

Action

No images have been added to edited topic.

You can use Windows Explorer to simply copy the files from the copy the reviewers have worked on back to your original project.

Images have been added to edited topic.

You can use RoboHelp's import function.

You will need to delete the original topic first which may pop up the warning that links will be broken. Do not select the option to delete the links, then when you import the replacement file, the links will be repaired.
You may find after import that some paths in the topic have become absolute paths to the copy project. If this occurs, use the method above after importing. Importing using RoboHelp's import function gets the images into your project. Then copying as above gets the topic in without RoboHelp making "helpful" changes on the way.

Table of Contents and Index

You may need to amend the table of contents and index dependant on what has been added to the help.

Step 7 - Check.

Step 7 - Check

Make your customary checks for broken links, correct appearance and so on. Then compile or generate your help.

Step 8 - Delete or archive the copy project(s).

Step 8 - Delete the Copies

Once you are satisfied that everything is entirely correct, either delete or archive the copies you created so that they are no longer accessible to anyone but yourself.

Topic Revisions

Date	Changes to this page
04 Mar 2005	New topic.