Document versioning is a tool that every project uses without a proper knowledge of why it’s done and how to do it. Here are some pointers on how to make it work for you.
Why Do We Version?
We know that documents will change over time, particularly in a design and build project, as the information that is used to fuel the creation of the document develops and changes itself over time. Also, any document created by the project is itself likely to be an input to the creation of some other document or project product, necessitating downstream change in that other document or product . We therefore need to version documents so that we, and others
- Know that the document has changed
- Are able to identify consequent changes caused by those changes
- Can be sure that any interrelated work tasks based on the document are using the same information
Any project document can be considered as having two lives that exist in parallel. The first life is a “private” internal one with the document owner/team, which takes place whilst the document is being created or revised. During this life, it will go through several re-writes until the owner is satisfied that it can be released to its intended audience. At this point, the document enters its second, “public”, life wherein it is used as a reference document for various processes and by various people external to the owning team. This is called publishing the document. Once published, the document enters another iteration of its private life, wherein it undergoes amendment and modification caused by changes to those informational inputs that were used to create the document in the first place. All this is illustrated somewhat crudely below (click the image for a larger version).
In practice, the private life cycle iterations may actually overlap as different versions of the document are prepared in parallel – for instance, if a particular downstream process has urgent need of a version of the document containing updates to a particular section while the rest of the document is being subject to a wider revision. This calls for a high standard of document management and team and individual discipline which is beyond the scope of this discussion.
How To Version Documents
Clearly, each published edition of the document will be a new version – that’s how the world at large knows that the information that it is using has changed. However, within the private life cycle, the document will also need to undergo versioning. This is because, while the document usually has a single owner it actually the responsibility of an entire team and forms part of a documentation set for which that team is responsible. Pre-publication versioning is therefore required because
- Intra-team review processes that determine whether the document is accurate and fit for publication need to know which version is being reviewed
- The document needs to be consistent with other documents produced by the team so that a consistent and coherent baseline can be formed for the document set
- Changes to the informational inputs need to be traceable to the particular draft document version so that their incorporation can be confirmed
From this, we see that we have a set of — possibly parallel — document production and review processes, each of which is expected to lead to a new published version of the document. With this in mind, the following is an obvious document versioning method:
- Each published document is numbered in sequence, usually with a multi-level version number that indicates the extent of that changes made since the previous published version (see below)
- The various incarnations of the document produced for internal review carry the version number of the target published document, the word “DRAFT” and the version number of that draft document
And yes – put DRAFT in capitals so people notice it and realise that they’re not looking at the finished article.
A simple example:
Internal document User Manual 1.0.0 DRAFT 1.0.0
Revised as User Manual 1.0.0 DRAFT 1.1.0
Further revised as User Manual 1.0.0 DRAFT 1.1.1
Published as User Manual 1.0.0
Revised as User Manual 1.1.0 DRAFT 1.0.0
Published as User Manual 1.1.0
Version Number Levels
Documents produced by projects tend to have a three-level version number as demonstrated above. I’d advise following this convention as
- You don’t know how many levels you’re actually likely to need
- It doesn’t hurt to have more levels than you turn out to need
- It will cause confusion if you change the levelling during the project
The change in version number is generally used to provide a clue as to the extent of the changes made to the document; however, it may also indicate a change to the significance of the information contained within the document. For instance, a change from 1.1.1 to 1.1.2 is likely to be a fairly minor modification, whilst a change from 1.1.1 to 2.0.0 may represent either a significant change to the document or a minor change that causes the purpose of the document to shift significantly (e.g. it now forms part of a baseline document set that addresses the next phase of delivery). With this in mind, it’s worth using version numbers that are meaningful to the document users rather than the document author (and the amendment log in the document itself will provide any necessary clarity). Some suggestions follow, in what is actually a logical order.
Third qualifier: Minor change with no alteration to the meaning and intent of the information conveyed by the document e.g. rephrasing of a potentially misleading passage, addition of previously missing content whose absence was identified, say with a “TBA” tag
Second qualifier: Meaningful change to the information that would be expected to cause some rework to downstream products e.g. changing an interface method from an XML message transmitted by a Web Service to an XML message transmitted via a Message Queue
First qualifier: Major change to the document that would indicate significant rework and/or additional downstream work e.g. change of the system’s ERP component from SAP to Dynamics AX
Note: as each qualifier is upgraded (1 → 2, 2 → 3 etc), it is sensible to zero the less-significant ones (e.g. 1.2.3 → 1.3.0, 1.4.2 → 2.0.0) to avoid confusion as to the sequence of versions in the document’s history.
Internal Review Documents
As stated above, these will simply be named after the current target version of the document, plus the single word “DRAFT” followed by the version number of the draft document itself.
Putting It All Together
Here’s the diagram from above, updated to follow all the excellent advice provided here (click for a larger version).
And That’s Just For Starters …
Realistically, we’ve only scratched the surface of document versioning here. However, there’s precious little that can be meaningfully written about it. The advice above will remove most of the confusion around versioning but your best weapon is to constantly think about your versioning whenever working on a team that creates products of any kind. If you can get your team to escape from the mentality of “it’s changed, therefore it’s a new version” and get them to think about where it’s a new version (Me? My team? The document users?), why (conceptual change, minor corrections etc), and to what extent it’s changed, you’ll be some distance ahead of the competition.