Search This Blog

Friday, April 20, 2012

Project Communications: GVSVCS (Free) Document Change Control System

[Also available as a Podcast]

Every project has documents. Dozens, hundreds, or even more. Some projects may be lucky enough to have an established document management system with version control. But many will not - and what do you do then? Or what if you do, but the client does not have access to the same system? Or you have a version control system - but people don't use it properly and you have a mess?

A very common scenario in the lifetime of any given document is that person (A)  writes a draft, sends it to B,C,D for review, receives feedback from each of them (separately or together), A updates it and the cycle continues until you have the finalized version. And quite often the files are exchanged by email.

Sounds simple, right? Well if you say yes - you have not actually dealt with the very real problem of version control (or change control). It is far too easy to lose updates when someone sends you a file that on the surface "looks like" the same one you had (same file name, mostly looks the same, you cannot see the changes because they were not marked or tracked properly etc). Or you overwrote B's updates with C's file when you saved the attachment. And even worse - if it is not being reviewed closely enough, that might not be caught until it is too late. Sound familiar?

There are many possible solutions to this of course - but I always like to think that simpler is better, because if you make it simple, people might actually use it. There are a lot of very expensive, fancy systems people just don't use - or don't use properly because they are difficult or tedious to work with.

Note that this is not a discussion on the "track changes" features of various document programs, which of course you should be using as well to track the internal updates. This is one level up from that, but just as important.

Introducing GVSVCS

Oh no, another acronym - and he must be selling something. No, it's just an acronym, coined by a customer staff person on one my earlier projects. Cheeky fella, but the name kind of stuck. And of course, GVSVCS is absolutely FREE. And it works on any platform.

GVSVCS stands for:

Gazza's Very Simple Version Control System. The beauty of this system that I still use and promote on projects every day is because it is simple, visible, and it works. It works for any situation where you have files and folders, in fact - not just documents. And it is easily adaptable to suit any project - anywhere.

GVSVCS is essentially a naming convention, applied and used by everyone on the team. Many of you may already have something similar, and if so - great! Keep on using it. But if you are struggling with lost documents and version control nightmares, please read on. And note that it is the spirit of the thing that matters - feel free to adapt this to suit your own project needs.

Under GVSVCS, every file has a consistent naming convention. Not overly restrictive mind you, just consistent. It goes something like this:

<descriptive part of the file name>_YYYY_MM_DD_[Vx.y]_INI_a.<Suffix>

example:

My Project Plan_2012_04_13_v1.6_gmn_a.MPP

It's that simple.

Let's break it down.

<descriptive part of the file name> is the meaningful title of the file. It may even include your own standards for naming in this part. This could be something like "Project Plan", "Status report template", "Communcations report", "Deliverable XYZ package" etc.

YYYY_MM_DD - the last date the file was updated by the person editing it. So if they received it on March 2, 2012 and were editing it until March 18, 2012 - the file name that they will be sharing for review should have the date 2012_03_18, and not 2012_03_02.

We format our dates MM-DD-YYYY or DD-MM-YYYY. Why use YYYY_MM_DD? It sorts better when you are looking at the files in your folder. The front part of the file name should be the same all the time - so it is very easy to see what the latest version of the file is when you sort by file name. 

Why not use "document date" from the file itself? Well - if you ever opened a file and accidentally clicked SAVE without actually making any changes, you will have changed the internal file date. So don't trust it to see what your "latest" version is. This is a big problem when you are passing around multiple versions of the same file name. And if you are dealing with team members or clients in vastly different time zones, things can get a little wierd figuring out the file dates. And sometimes the date is modified when you saved the attachment from email. So again - don't trust that date for anything to do with proper version control.

[Vx.y] is the version number of the specific document. (This may be optional in some situations, like status reports). So if you are working on a new draft of a document, the number should be be incremented when you start applying edits from the last review session.

One convention we use on our projects is that drafts all start with 0.01, 0.02, 0.03 etc and the first issue (signed off version of the document/released deliverable to client) is 1.00. After that, 1.01, 1.02 etc. We only jump to 2.00 when there is a significant change, as in a major change request or architectural change. 

Why 1.00 and 1.01 instead of 1.0 and 1.1? The simple answer is that it sorts properly. And if you have 99 versions, you should really be on 2.00 by now anyway, or use a 1.000 system instead. But establish that from the beginning.

NOTE: You could choose to have [Vx.y] ahead of YYYY_MM_DD. It's your choice. But in my experience, versions happen sequentially anyway, so the date really takes precedence when you have multiple versions of V1.5. And also - if you are not following 1.00 version numbering but using 1.1-10, 1.11 etc, then you have the sorting problem all over again. So it is simpler and less error prone to have the YYYY_MM_DD part first.

INI - These are the initials of the last person who edited the file (i.e. you). You can't believe how much time can be saved by knowing who edited the document when you need to ask questions, because sometimes they may not have updated the change table - or the file type does not support internal version/author info.

a - It is a busy world and things move fast. And sometimes, you are working on an important document and want to save snapshots of your work, so you won't lose a huge amount of effort if you mess something up. the "a" represents a sequence, as in a,b,c,d...z. If you (or multiple people) edit the same document (or save snapshots) multiple times in a day, it can be very helpful to include the sequence. If you receive file on 2012_04_12_gmn_c.DOC, then you would copy/rename to 2012_04_12_YOU_d.DOC and start editing.

On very busy days where I want to preserve frequent snapshots of new work (tricky, hard to remember exactly what to do all over again if I lost part of it), I have got as far as m,n,o,p. And sometimes I have been working on sequence g and had to go back to e (not f) because instead of cut-and-paste I only "cut" at some point, but the stuff I had deleted was still in e. Save often, and save versions!

Of course you can cleanup and remove all the extra versions days later, but if and when you need them while you are working - you will have them. If you don't save versions - it may be a long night ahead.

Variations

For some types of files, you might apply some specific naming conventions to the first part of the name. These are of course are up to you - but here are some examples from recent projects I have worked on:

Deliverable packages:
<CustAbbr>_<deliverable#>_pkg_<Vx.y>[_YYYY_MM_DD_INI].ZIP
Most of the time with these set deliverables we don't use the part in [brackets].

Requirements Documents:
<CustAbbr>_<deliverable#>_spec_<Vx.y>_YYYY_MM_DD_INI.ZIP

Test Documents:
<CustAbbr>_<deliverable#>_test_<Vx.y>_YYYY_MM_DD_INI.ZIP

Note: We include <CustAbbr> because we are usually working with multiple clients and multiple projects at the same time. You may not need to do this.

Note these vary slightly from the "general rule" above, but if you agree on a standard and stick to it as a team for a given type of file, it tends to work well.

Extension - Folder Structures

Documents are one thing - but what about folders? I personally find it easier to find things when a simple, standard folder structure is setup. And when you have a mix of different related files that you want to keep together, where better than a standard-named sub-folder?

We frequently have several types of files we need to keep together - the versioned deliverable package, the test document, and often many sample files. Or versions of a draft specification and a number of supporting reference documents as inputs.

Again - you may already have your own well-defined system. But if you don't, here are some suggestions:

ProjectName/
           Deliverable Name-#/
                       Specification/
                              v0.01/
                              v0.02/
                              v1.00/
                              v1.01/
                       Deliverable/
                              v1.00/
                              v1.01/
                              v1.02/
                              v1.03/
                              v1.04/
                       Test Results/
                              v1.00/
                              v1.01/
                              v1.02/
                              v1.03/
                              v1.04/

You may have many more levels and branches, but this is the general idea.

Of course, if you are tracking different things like status reports, it makes more sense to use a date as the grouping folder name (Year and month, or Year date month), i.e. YYYY_MM or YYYY_MM_DD.

Why 1.00 and YYYY_MM_DD for the folders? Same reason as the file names. It just sorts naturally, and will literally save you dozens or more hours during the project "trying to find that file", or making sure you are looking at the latest version.

Making it Stick

It is a short, small learning curve to use GVSVCS (or your own adaptation, call it what you like, if you actually call it anything). But people will still take a little time to get used to it. However, it is very important that you kindly but firmly make sure that it is being followed early on - so that it becomes an easy habit. If you let them go for a long time fixing their file names for them, they will not learn the habit and you will get increasingly frustrated. It works best when everyone is consistent. And it's not that complicated - so there is no real reason why they shouldn't do it!

Summary

GVSVCS is the system I live with and use every day - in my own PC file system, and on the shared document management systems we use to run projects. And the team members use it also - it simply becomes part of the communication culture. (And on projects I have managed, it is actually part of the Communication Plan as well). It is simple, and it works. If you build something difficult, people just won't use it.

And again, for those who do have wonderful version control systems - that's great, keep on using what works well for you.

But for the rest - be simple with your tools and processes, and be successful. 

Good luck with your projects, and managing all those documents!


Gary Nelson, PMP
Gazza Consulting Services