So here’s a topic that you don’t see discussed very often. Document version numbers might seem like a trivial concept – a subject upon which there is little to be said – but they are a real bug bear for me. Let me explain why.
Most people tend to use the following version numbering scheme:
- 0.1 – first draft
- 0.2 – next draft
- 0.3 – next draft
- 1.0 – signed off/approved version
Now that’s all well and good up to that point. But inevitably (and increasingly in an agile world where change is to be encouraged, nay embraced)… things change, and version 1.0 needs to be revised.
So version 1.0 gets updated to version 1.1, and maybe version 1.2, and so on. But at this point it’s never clear (to me at least) whether version 1.1 is a draft for approval or an approved update to version 1.1. In order to be sure, I have to open the document and check the version history, and even then, authors are sometimes not rigorous enough to state explicitly whether the document amendment is signed off or not.
And even if you have a clearly stated convention that says an approved document must be “something dot zero”, I don’t like the way that the numbers stack up. So, for example, version 1.3 is supposed to be a draft working towards version 2.0, but to my mind the “1” associates it more with version 1.0 than version 2.0.
So I don’t like this version numbering scheme. But there is an alternative that I do like. I discovered it on a project I worked on a few years back and I’ve tried to introduce it everywhere I’ve been since then.
It’s very simple – it goes like this:
- Issue 1 Draft A – first draft
- Issue 1 Draft B – next draft
- Issue 1 Final (or, alternatively, Issue 1 Approved) – signed off/approved version
- Issue 2 Draft A – first draft of a change to Issue 1 Final (working towards Issue 2)
- Issue 2 Draft B
- Issue 2 Final
- …and so on
There, easy! Here are the benefits:
- Drafts are clearly labeled as drafts
- Final/approved versions are clearly labeled as such
- Drafts are associated with the final version they are working towards
The only downside is that you run into trouble after 26 drafts!
Wow! That was a quick article. I guess I can have some lunch now. Oh, hang, on, I have a few extra thoughts.
Always Version Control Your Documents
If I think I am likely to share a document with others (i.e. it’s not just purely for personal use), I will version control it as a matter of course.
That doesn’t mean I use a formal template for every document. Sometimes it’s as simple as adding the version number to the file name, rather than inserting an explicit document control section within the document, and it takes seconds to do.
Don’t Use Drafts Unless the Document Will Be Approved
If I am creating a document that I know I will share with others, but it’s not a document that will be going through any formal approval process, I tend to give it a simple numerical version number (v1, v2, v3 etc.). There seems little point in calling something a draft if it’s never actually going to be approved (or baselined).
Mark “In Progress” Documents as such
When I’m working on a version controlled document, I always add a suffix “WIP” onto the file name to show that it is Work In Progress. When I am ready to share/issue the document, I remove the “WIP” suffix (and also add details of the version to the version history section within the document). I do this even for draft documents, and even if the document is only stored locally on my computer, where no one else can see it. In this way, I can easily spot the difference between a document that’s in progress and one that’s complete. It’s especially useful if I’m working on several documents at once, and really helps on projects where I am storing work-in-progress on a shared drive.
Marking Up Changes
Marking up changes is a common technique to show your audience what has changed in a document. Microsoft Word’s “track changes” facility has improved considerably over the years and is a very useful markup tool, although I always feel somewhat politically conservative every time I “reject change”.
The trouble with “track changes” is that it shows each and every change you have made verbatim, and sometimes that can impair readability. Sure, you can improve readability by accepting an addition or a deletion here and there, but that somehow feels like you are subverting the tool, trying to trick your audience.
Recently I have been marking up my changes manually, simply by changing the font colour, and thus avoiding such subversive feelings. This has the added benefit that I can choose my markup colour rather than having Word choose it for me. And my favourite markup colour is…(wait for it)…pink! Specifically, magenta. Why magenta? Because it’s the one colour that shows up well both in colour and when printed out in black & white. Blue and red are both too dark, but magenta is just right. Magenta markup has the added benefit of providing an ideal ice-breaker for document review sessions – I’ve lost count of the number of times I’ve had to explain why I use it.
The other mark-up dilemma I often face is exactly what to mark up. In Issue 2 Draft B, do I show just the changes from Issue 2 Draft A or all the changes since Issue 1? Some of my audience may have seen Issue 2 Draft A and only want to know what has changed since then. Others might not have seen the previous draft and are only interested in what changed has since the previously approved version. Usually, I mark up all changes since the previously approved version, which seems to be the best catch-all. Sometimes I use different colours to show the changes for each draft. I never show mark-up from before the previously approved version though – that would get way too confusing.
A Living Document
An alternative to version control is a living document. In a previous article I described a Functional Specification which resided on a shared drive and was continuously being updated during the life of the project. The document as a whole was never approved – rather, the acceptance criteria within it were approved individually by adding a date stamp against them.
I like this lightweight approach to approval – it saves a lot of time and effort and speeds things up considerably.
One of the challenges of agile is to see just how little documentation you can get away with and still deliver working, maintainable software. There is much talk of index cards and whiteboards, and of the code being the documentation.
As a Business Analyst, it’s hard to imagine giving up documentation altogether, and I’m not completely convinced it’s the right thing to do (especially not on my current project, which spans four continents). But agilists are right to challenge the document-heavy approach. If I do hang on to my documentation, I’ll be making sure I’m doing it for the right reasons – as a means to an end – to deliver working software – not as an end in its own right. A good book on this topic is Agile Documentation by Andreas Ruping, who talks about documentation being “light but sufficient”.
But just think, if you did have no documentation, you wouldn’t have to worry about the version numbers, would you?