6 version control best practices

Team projects require shared documents and programs, but poor version control can slow progression. See six best practices for version control.

By Tyler Bullock February 3, 2015

Anyone who has worked on a team project knows version control on programs and documents are vital to the overall project’s success. Although version control will probably not be identified as the major cause of a successful project, it can easily become a key contributor to why a project struggled or failed. Here are six best practices for version control:

1. Archive documents

One of the most important aspects of document control is saving the files to a centralized location with a proper backup and recovery process. If a file is saved to a local hard drive and should that computer be damaged or stolen, that information will be lost.

2. Mark documents in progress

Documents in progress should be marked to notify everyone that it is locked for editing. The current document should not be used, and an updated version can be expected. This will prevent someone from referencing a stale document or attempting to edit the same document. If two people edit the same document concurrently, a conflict will arise. If conflicts arise, manual integration will likely be needed.

3. Save documents under a new name

Two different documents should not have the same name. Anytime a document is updated, it should be appended with a date or version number. If the document has a header, fields such as date, revision number, and author should be consistent with the file name.

4. Locking final documents

Once a file is ready for transmittal, it should no longer be editable. For example, save a Microsoft Word document as a PDF and place it in a new directory. Some proprietary software files have security settings that allow a user to prevent further modifications. If transmitting a group of files, converting them to a zip file will make it easy for other members of a team to identify the finished documents.

5. Organization

A directory structure should be reviewed before a project begins. If a new person joins the team, he or she should be familiarized with the structure. One directory should be set aside for documents that are a work in progress. If multiple team members are accessing and updating the same file, only one master file should reside in that directory to avoid confusion. Snapshots of that file should be archived on a daily basis. A separate folder should be set aside for finished and locked documents. If a finished or locked document needs further modification, remove the file from the directory until it is complete. If a file does not exist in this directory, other team members will know it is not finalized.

6. Communication

Perhaps the most important aspect of version control is communication among team members. A simple e-mail to notify other team members of progress or updates may alleviate any confusion. Taking two minutes may save two days of work.

Many companies incorporate different systems for document control. Shared network drives allow one copy of each document on a central location, but this allows easy deleting or removing documents. Cloud storage systems, such as Dropbox, downloads all files within that directory to a local laptop folder. Files are not updated to the cloud until a user saves the document and connects to the internet or network. Also, if a user has a document open, someone else may update the document and the user will not be notified that it has been updated. Other systems include centralized or distributed repositories. Users should be familiar with their document control system and know the advantages and drawbacks.

This post was written by Tyler Bullock. Tyler is an engineer II at MAVERICK Technologies, a leading automation solutions provider offering industrial automation, strategic manufacturing, and enterprise integration services for the process industries. MAVERICK delivers expertise and consulting in a wide variety of areas including industrial automation controls, distributed control systems, manufacturing execution systems, operational strategy, business process optimization and more.

MAVERICK Technologies is a CSIA member as of 3/5/2015