Creating IT Dept Guidelines
When it comes to version control procedures, the lack of
formal guidelines is a serious issue for Technical Writers.
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:
- They put a copy of the file on a local machine.
- 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.
|
