Productivity Tip

Refresh your project regularly! While working on a project in a team always click on Refresh Project in the Project menu whenever you switch to a new topic to make sure that you see the current version of the Table of Contents and Project Files.

•Professional and Server versions only:
Multi-user editing is only supported in the Professional and Server versions of Help & Manual. All users accessing the project must be using the Professional or Server version of Help & Manual.

•Uncompressed XML save format only:
Projects must be saved in the uncompressed XML (.hmxp) format for multi-user editing to be possible. The compressed .hmxz format cannot be used because it is stored in a single file and it is necessary to access individual topic files for multi-user editing.

•All projects and sub-projects must also be saved as uncompressed XML:
If the project has any merged sub-projects they must all also be saved as uncompressed .hmxp projects. You cannot have any .hmxz sub-projects if you are going to use multi-user editing.

Active VCS support:

Multi-user editing is also supported when your project is linked to an actively-supported version control system (Microsoft Visual SourceSafe and 100% compatibles). When your project is actively linked to a VCS repository all the multi-user access capabilities are then handled by your VCS, but this will not make any difference to the way you work on your project. All the topic and project editing and access features work in almost exactly the same way as with normal multi-user editing as described in this chapter.

Passive VCS support:

In addition to active VCS support included in Help & Manual, you can also store your projects in any Version Control System "passively" and still use multi-user editing. Then Help & Manual uses its own multi-user editing. See Using any VCS "passively" for details.

Improved remote editing capabilities:

Remote editing – i.e. working on projects stored on a remote server – is considerably better and more robust when you use active VCS support, both for single-user access and for multi-user access. When your project is actively linked to a VCS you work on your own local copy that is linked to the copy in the VCS repository on the server. This means that only the changes need to be transferred between your location and the server, and that only when you open your project (changes on server are transferred to you) and save your own work (your changes are transferred to the server). Everything else is local.

Getting the latest version from the VCS repository (database):

When you use the Refresh Project function when you are working on an actively-linked VCS project, Help & Manual automatically updates any necessary changes from the current version in the VCS repository. This also happens when you select a topic for editing, so you can always be sure that you are working on the latest version.

Save/check in when you finish editing a topic:

When you have finished editing a topic you should save your project to make the topic available to other users again. Until you save your changes will only be local, they won't be written to the VCS repository. If you are using manual check-out you must also check the topic back in to make it available to other users again, otherwise it will remain checked out.

Check out the TOC to edit in manual mode:

If you are using manual check-out in an actively-linked VCS project, you also need to check out the TOC to make any changes to it. To do this, check out the Table of Contents heading in the Project Explorer in the same way that you would check out a normal topic. You need to do this to create new topics, to move topics, to delete topics and to edit topic captions in the TOC.

Link your project to the VCS before you begin remote editing:

If you know you are going to need to edit your project remotely it is best to create your local linked copy from the VCS repository before you go on the road, if possible. This will avoid the need to download the entire project over a slower connection before you can start editing. See the chapter on using version control systems for more information.

Note that this is not possible if you are using a VCS "passively" because then there is only one local project. Editing that remotely is not recommended. It is better to log in to a machine on the local network using Remote Access.

Style standardization is a common problem in team projects: you generally don't want individual authors making arbitrary changes to the styles of your standard layout.

If you want to make sure that the same styles are used by everyone working on the project it's advisable to store the styles in a project repository and link the repository to your documentation project. Then only give the team member responsible for layout access to the repository so that only she or he can edit the project styles.

See Working with Repositories for instructions on how to set this up for your project.

This is a very important tool when you are working in multi-user editing mode. It updates the display of the project and the TOC on your screen so that you can be sure that you are seeing the current version, including any changes made to the TOC by other users who may have moved, deleted or renamed TOC items.

Refresh also updates the contents and lock state (read-only or read-write) of the current topic displayed in the editor.

Always use Refresh Project before making any changes that affect the TOC (renaming, moving, deleting and creating topics).

Always save your project directly after making changes that affect the TOC to make sure that there are no conflicts with other users' edits that you need to resolve.

See Creating, renaming, moving and deleting topics below for more details.

Just store the project on a network or server drive where all authors have read/write access and start editing as normal.

You will only notice a difference if you try to edit a topic that someone else has open – then you will get a message telling you that the topic is open and is not currently available. Help & Manual will never allow two different versions of the same topic to be created and it will never allow two users to edit the same topic at the same time. This applies even if you have not saved your project.

When you select a topic that another user is already working on you will see a red bar with a READ ONLY warning at the top of the editor screen and the topic will be grayed out in the TOC.

If another user starts editing the topic while you are viewing it you will not see the READ ONLY bar immediately. However, if you then try to edit the topic you will get a message telling you that the topic is now being worked on and then the READ ONLY bar will be displayed.

Custom display color for read-only topics:

You can set a custom color for displaying read-only topics in the TOC to make them easier to identify for you. Go to View > Program Options > Editor and change the setting for Display color for read-only TOC items.

Help & Manual never allows you to edit the content of topics being worked on by other users under any circumstances, even if you have not saved or refreshed your project.

However, when you make changes in the TOC in multi-user mode you are working on a local copy of the TOC. The changes are only written to the actual project file when you save the project. If another user has made changes to the same TOC entries you will have a conflict and a dialog will be displayed asking you to resolve the conflict – you must then decide which version of the changes to keep and which to discard.

User Refresh Project to avoid TOC conflicts:

To avoid conflicts you should always select Refresh Project in the Project tab before making any changes to the TOC. This will update your local copy of the TOC with the current main version.

Refresh also updates the contents and lock state (read-only or read-write) of the current topic displayed in the editor.

Creating new topics:

You can create new topics just as you would when you are working on a project on your own. New topics cannot conflict with changes made by other users so you can always create them. Of course, if you choose a topic ID/topic file name that conflicts with an existing topic you will not be allowed to create the topic.

Renaming, moving and deleting topics:

Always select Refresh Project before moving or deleting topics or renaming them in the TOC. This ensures that you are viewing the current version of the TOC in the main project file and prevents you having to resolve conflicts with your co-workers.

Once you have done this you can move and delete topics just as you would when you are working in single-user mode.

Even so, it is generally advisable to check with your colleagues before moving or deleting topics that others have also worked on! If in doubt make a copy of the topic with File > Save Topic to File in Project > Manage Topics before deleting it.

You can perform global search and replace operations normally when other users are working on the same project as you. You will be able to find terms in topics that other users are working on but you will not be able to replace them there until the other users save their work and stop editing the topics.

Your settings in the Configuration section of your project are not managed in the same way as your project content. Any changes you make here are made without warnings or locking. Anyone who makes changes here and saves the project will overwrite the current settings with the new settings.

When you are working in a team the Configuration section should be the responsibility of the project manager. Always check with your project manager or co-workers before changing anything in your project configuration!