Using Version Control Software

Many IT Managers face the challenge of managing hundreds of files with several tech writers working on them at the same time.

For a Documentation Manager, there are several options available to remedy this.

Most use Microsoft SourceSafe, CVS or PVCS to manage this thorny process.

Creating IT Dept Guidelines

When it comes to version control procedures, the lack of formal guidelines is a serious issue for Publication departments; for example, there may be no "best practice" guidelines for "getting" versus "checking out" documents.

With certain software packages you can "get" a copy of a file in read-only mode and then make it write-able. This overrides the security "check out" feature of the system which can later prove counter-productive and create even more confusion.

Using Version Control to Checkout software and documents

Checkout procedures have several purposes:

1. They put a copy of the file on a local machine.
2. They lock the file; only the user who checked it out can check it back in.

This process protects your team from itself it alerts the rest of the team when someone is working on that file.

Version control software protects team members when two or more writers attempt to update a document simultaneously. Should this happen, they risk losing one writer's contribution, as the last saved version will overwrite the previous version.

Using CVS

CVS doesn't truly support a lock system. Instead, its default mode is a 'merging model'. You can use a lock system with CVS if you use the -L and -l options to the Admin command.

Multiple users can check out the same documents and then attempt to check them back in. When working in ASCII modes, such as HTML, this works fine as it will calculate your differences from the last version and apply them. Depending on your product version and platform, it can figure this out quite well.

However, if there is a conflict it will stop you checking files back in, and force you to manually reconcile the difference.

RCS and Microsoft SourceSafe offer locking.

Note: You can override the checkout lock, but use this in emergency situations only, e.g. when someone leaves the company and forgets to unlock their files.

When you override a lock, ensure that the locker has checked in the most recent version, or you'll lose the work.

Managing versions by product line

When preparing documentation plans, one approach is to delineate your documents based on product lines and give each writer their own set of files to manage. You then have to ensure that there are no files shared between products.

If you don't control this, you will end up with writers working on the same files, and everyone having copies of the files on their local drives to edit. Documents will clash when they are checked back in.

Needless to say, the larger the team, the more important a clearly defined source control procedure is followed.

Your Thoughts?

What are your thoughts on this? Drop me a line at ivan at klariti dot com