In part 1 of this formerly two-part, now three-part1, series of posts, I explored what can happen with document versioning if there's little or no discipline.

In this part I set out to offer some simple suggestions to make versioning of documents predictable and understandable, which will make the documents themselves more accessible.

The following small set of rules on versioning can greatly improve the quality and traceability of your documents. In summary, these are:

  1. Use only one versioning system for all your project's artefacts.
  2. Use a document properties to record version information
  3. Maintain documents in a networked location, and use URLs.
  4. No embedded documents
  5. Remove older versions out of the way.
  6. No version information in file-names.
  7. Use a project librarian
  8. Make documents easy to get by making them easy to produce properly.

The first 5 of these is covered in detail below, and then in part 3 I will discuss the last 3 and how to make things even easier by using a dedicated revisioning tool – i.e. the one your software developers use – for your documents too.

Use only one versioning system for all your project's artefacts.

This might sound obvious, but it's not always the case in practice. Different contributors to your project will have different understandings of what each designation.

  • Version 0.9 to some is just a version number on a draft document, but to others it's reserved for the version that's to be sent out for approval.
  • FINAL means a completely finished document to me, but some colleagues have used it to say this version is the last one to be published to get the very last approvals
  • _v0.5_JDComments is version 0.5 marked up with comments by John Doe. To me, this is not a new version, though I've seen others regard it as one (i.e. send it around as a version to be reviewed, rather than incorporating the comments into _v0.6).

The versioning system you use should be simple, so that all interested people don't have to try to remember loads of different rules. One recommendation is to separate the mechanism you use to distinguish one version of a document from another, and the mechanism you use to identify the stage the document is at.

For example:

  • x.1, x.2, etc. denote documents in draft, incrementing with each new version that is published. These will continue incrementing (x.8, x.9, x.10, x.11, … x.19, x.20, … x.99, x.100, etc.) until the document has been fully approved.
  • 1.0 denotes the first fully approved version of the document. 2.0 is the second fully approved version. And so on. If an approved document is to be amended, then the minor number is to be incremented (1.1, 1.2, 1.3, etc.) until that version has been approved (at which point the major number is incremented and the minor reset to 0).
  • The status of the document is represented more clearly, though. A document can only be in DRAFT, FOR APPROVAL or COMPLETE states. Alternative words could be used for COMPLETE, such as APPROVED, FINAL (though, I wouldn't recommend either of those!), LIVE, etc. Using, the x.y notation, if y is not 0, then the document's state is either DRAFT (still in the works) or FOR APPROVAL (author thinks it's complete, but has yet to get important people's agreement). Once a document is COMPLETE, the y value is set to 0 and the x value is increased by 1.

There really is no need for it to be more complex than that. In fact, I prefer a simpler arrangement: version numbers are just integers (1, 2, 3, 4, etc.), and the document state is the only indicator of the document's progression.

Use a document property – where supported – to store the document's version information

As it makes more than just sense for the version information of a document to be expressed somewhere within the document, one often finds it in multiple locations: title page, page footers, page headers, introductions, etc.

If these are each individually typed into the document, then each time the version is to change, it needs to be manually edited in all places in the document where it's expressed. Some people will miss some instances, and others will decide that it doesn't need to be updated until, say, a certain milestone is achieved. Both of these scenarios are problematic.

Microsoft Word, LibreOffice Writer, OpenOffice.org Writer and many other document editing utilities allow for the configuration of fields that can be set in the document's properties and then referenced throughout the document's text. If the author updates this "field" or property and then instructs the document to update all references to it, all expressions of the document's version within it will be updated.

Maintain the document in a networked location, and use links.

Don't let documents be sent around as attachments to e-mails. No matter how hard you try, there is no way to make sure that all relevant people will pull up the correct version of all documents at all times. If, however, you send only a link to the document, then all recipients of your notification will pull up the linked-to document (if they haven't saved it off somewhere!).

In order to reinforce this I often put the following statement in a prominent location of a document:

This document is maintained at <documentAddress>. The only official version of this document is at that address. If you are reading this document from some other location, you are advised to retrieve it from the above address in order to ensure that you have the most up-to-date version.

In this scenario, copies and printouts of documents are immediately obsolete, not necessarily because the official version is immediately different, but because the copy or printout cannot track any updates to the official version.

In addition to this, I would strongly recommend that everyone in the organisation have (at least) read-only access to the location where the document is being maintained without having to raise a specific request for this. This is very important. If there is no compelling reason to restrict access on documents to legitimate members of the organisation, then all documents should be accessible to all users without the need for instance-by-instance granting of permission. It's bad enough if someone has to supply a username and password every time they want to read a document, it's worse when that person has to wait a number of days to be supplied with a username and password. In this case, a number of risks arise:

  • A legitimate reviewer of the document can't review it;
  • Your deliverable is delayed while you await the granting of access;
  • Or your reviewer has to provide comment on an unofficial, obsolete version of the document that had to be e-mailed to them (see above).

This latter risk is especially important, as it might seem minor, but without rigorous application of your rules, it is the slippery slope that will make a networked location of the documents pointless.

Think open: unless you have a good reason to hide it, you shouldn't allow it to be hidden.

Don't embed documents

Don't allow the embedding of documents within documents.

This may well be a handy way to pass documents around, but it comes with problems.

Documents aren't directories. That you can put one or more documents into another doesn't mean that you should. Embedded documents can't be maintained as flexibly as documents in a directory.

Changes to embedded documents aren't independently trackable.

Many would see a change to an embedded document as not requiring a version increment, but then others would not know that the embedded document has been changed.

Comparing different versions of an embedded document, each in a different version of the containing document is, at the very least, a challenge.

And, if you're in the habit of passing around links to a document, then there's no need to embed it.

Remove older versions away.

Don't keep older versions of a document (even the immediately previous version) in the same location as the current version. When someone lands in the directory or folder where the document is maintained, there should only be one version of the document available. This will make it completely clear as to which file should be accessed: there can be only one.

If you need to retain older versions, and if you aren't using a revision control system that does this for you (see part 3), then copy those older documents into a different directory. If that different directory is to be a sub-directory of the document's normal home, then it should be named such that it's clear that live documents don't reside in there. (Call it Archive, previousVersions, Obsolete Documents or something like that.)

In part 3 (of 2!), I finish going through my suggestions, and then will discuss one way of helping putting them into place.

Footnotes:

1
Dreadful planning. This series initially started out as just 1 post, became a two-parter when I saw that there was more to say, and now it's a three-parter, largely because I've said too much!