A New Approach to Document Version Numbers

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.

The insecurities of a version 1.1 documentThe Problem

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.

The Solution

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.

Agile Documentation

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? :)

31 thoughts on “A New Approach to Document Version Numbers

  1. Karen Greaves

    Thanks Tony – i am going to start using the WIP designation today. I usually start revising my documents about 2 minutes after issuing them to the team – so this will really help me organize the in progress vs the issued.

    Reply
  2. Joy Campbell

    ITony, thanks so much for sharing. It may have been a “short” article, but there are so many great tips that you shared! I had no clue the pink printed differently in black and white.

    I have been known to have a “rainbow” document when changes muyltip[e changes are made at different points in time. I really need to remember to go back at the “signed-off” version and start over with all black.

    Thanks again!

    Reply
  3. Patrix

    Interesting approach, but I wonder to which extend your initial problem with version numbers come from the fact that you are using the same “identifier” for both the version under which the document is published/released and the revision which is more like the build number in software releases. I’ve started to clearly differentiate these two concepts and have found live much easier this way.

    Reply
      1. Patrix

        I’ll try to:
        – Every save (or at least check-in in case you use any kind of version control or Sharepoint or such) increases the revision number (mostly automatically) resulting in a clear and uniquely identifiable document
        – When I’m ready to publish either a draft or a final version, I make a copy of it and label it similar to what you proposed above (e.g. “Requirement Specification V1.0 Draft A” etc.). This copy then gets published (which usually means that I distribute the link to whoever is expected to provide feedback).
        – Any additional changes lead to yet another revision which may later be published again.

        Reply
  4. Iustin

    In a ISO 9001 certified company/organisation this should not be an issue (versioning) – while system procedure Document control (as required by ISO 9001) states how documents are held under control. including versioning, changes etc.
    Using properly a standrd usualy solves 99% of problems. Not doing that generates “new revolutionary methods” of doing what one is supose to do in the first place (see “agile” and PMBok; PMBok states that a PM should manage team, time and change requirements in most efective and efficient way – using various tools. Most PM’s dont do that – so they invented agile!)

    Reply
    1. Tony Heap Post author

      Hi Iustin,

      Thanks for your comment.

      As far as I am aware, ISO 9001 doesn’t mandate any particular version numbering scheme, it just mandates that you should have one. The one I suggest above could be adopted by a company within ISO 9001.

      And I don’t agree that merely having a documented numbering scheme eliminates all problems/confusion. Imagine that my ISO 9001 certified company uses the following scheme:

      – First draft must be labelled “version 3”
      – Second draft must be labelled “version dog”
      – Final approved document must be labelled “version green”

      I would struggle to train my employees to follow this numbering scheme, even if it is well-documented. And I would have even more trouble explaining it to my external customers/partners. I have a much better chance of ISO-9001 compliance if my numbering scheme is as intuitive as possible.

      Reply
      1. Iustin

        Hello Tony – and thanks for your reply.

        Just two observations:
        1 – not “should” but “shall”; ISO 9001 says at 4.2.3: “Documents required by the quality management system shall be controlled.” Mandatory. This leads us to
        2 – “mearly” would not be the word of my choice. Not to mention that I didn’t say that your scheme (a very good one acctualy) can be replaced with something like numbering the documents. Numbering the documents it’s a solution of choice for some organisation – a mearly basic one! :)

        What I am saying is that using a good scheme (like yours) in a management system that is documented, communicated and addopted within the organisation solves the problem.
        You say “I would struggle to train my employees to follow this numbering scheme” – well, that IS the problem! You struggle to feed the goose with plutonium – but the poor bird works with corn! In my practice (management systems consultant that is) I’ve learned that ppl are the ones that can build a system that works. Not the boss!
        Your scheme is great – but its YOUR scheme. Make’it theirs!

        Reply
  5. Katie Metcalfe

    Thanks Tony! Like the tips, especially the magenta usage. I like the WIP extension and am going to try that as well. Your methods does create some clarity. I’m going to try it.

    Reply
  6. Yaaqub Mohamed(Yamo)

    These are some great tips Tony. Thanks for sharing your ideas and insights on this topic. This may seem like a trivial topic at first, but can cause considerable agitation if not managed properly.

    Having lost a couple requirements document myself, (due to the famous ‘your word has crashed’ exception) I would to like suggest a couple additional techniques. One is to always have a local disk backup (always; along with the shared-space copy) and then adopt a naming convention to work through your drafts. And for any document that I am working on, I create an “archive” folder, and continue to save the older versions in this folder. This makes your main folder clutter free and allows you to focus on the ‘document at hand’.

    I have added your book recommendation to my amazon’s “wishlist”, and will try to interview its author on some best practices. Anyways, thanks once again for sharing this with the community, Tony. Looking forward to reading more posts from you.

    Reply
  7. Nick Panagopoulos

    I love Tony’s articles. You tackle the part of the job that isn’t what we signed up for, but part of our daily lives.

    I like your simple approach: Issue 1 Draft A. The numbers specify the version, and the letters the Draft, so the 2 don’t merge…simple but an A+ for UX design!
    (After 26 drafts, you can use AA – excel does that too with columns).

    I also want to iterate that the revision history section is still important. Tell people what changed with each Issue.
    @Tony, do you track how each Draft was updated in the document? I can see how it’s important during the review cycle (“Hey, what changed since I last looked at your document? Were my comments incorporated?”)…but once approved, the revision history for the ‘Issue Approved’ (changes since last approved version) is more important than the draft.

    Tracking Changes.
    MS version numbers change based on the user ID. Change your name, and you automatically get a new color, and MS word even thinks you’re a new author, so you can turn on/off updates for each revision, as you wish. I find this way more useful than maintaining a color scheme yourself. Just approve all changes in the document after each approved version. You can use the convention ‘Issue 3 Draft A-NP’ (NP are my initials) or NP-Issue 3 Draft A.
    For MS Word 2003: Go to Options -> Tools -> User Information tab -> Change the name.
    For MS Word 2007: Go to Start -> Word Options (at bottom of popup) -> Popular menu -> Change the User Name.
    Sorry, don’t have 2011, but I imagine it’s similar to 2007.
    The problem with this is that you have to constantly remember to change your User Name for each document you update. This becomes a bear when I’m updating more than one document at a time.
    Also, MS Word does not like when you have too many authors on a document. I have experienced corrupted documents (in Word 2003) in the past when there are too many versions, so the solution is not perfect.

    Approved version:
    I notice that documents are the place people go to find answers, but not all people. My customer would just ask me the question instead of looking it up. I’m much more intimate with the document, so I can find the information much easier than they can. The question I get more than, “What does the system do?” is “Why does the system do that?”.
    I like keep all changes, and not approving them, because the revision history is important when trying to understand ‘why’… or you can start tracking all the decisions (there seem to be more decisions than requirements).

    Again, great article Tony!

    Reply
    1. Tony Heap Post author

      Exactly what changes I mark up really depends on the specific circumstances. At the moment I am not tracking any changes up to and including Issue 1 Final. After that I will track all changes made since the last approved version. So Issue 2 Final will show all changes since Issue 1 Final. Sometimes I just mark up all the changes in one colour but sometimes I mark the changes from each draft in different colours if I know that the dev team has been working to an intermediate draft – then they can see what changed since then.

      That MS Word tip is a good one. Not so good for me at the moment as we are writing our specs in Visio!

      And I agree, the version history is crucial. Because my memory is useless, I make sure I keep the version history spot on for my own benefit, never mind everybody else! :)

      Reply
  8. Michelle Swoboda

    Hi Tony, a great and timely article.
    The last two companies that I have worked for have used SharePoint for versioning the documents. This works quite well as it is auto versioning, so you don’t have to change the title. You can also access any version before to get back to an original question about something that has been changed.
    Having used many versioning models before, I would say that this is my favorite and most fool proof.

    Reply
    1. Tony Heap Post author

      Hi Michelle,

      Thanks for your comment. I have wondered about using SharePoint for this (we do use SP but not for version control). I do have a couple of questions though:

      1) If the file doesn’t contain the version number, once the file is away from the SharePoint repository (e.g. if you email it to a third party who can’t access SP, or if you print it out), then how does the reader know the version number?

      2) How do you add comments to say what has changed in each version? Does SP allow you to do this, or do you have to put it in the doc itself?

      Reply
  9. Michelle Swoboda

    Hi Tony,
    The way we worked it with versioning for files away from SharePoint, is two ways. Anyone who had a stake in the document had access the SharePoint, so they changed the file there. The other way was to have one person own the document and have the changes forwarded to them. They both work!
    We also have a version change on the second page of each document. Anyone making changes must detail what they are changing.

    Reply
  10. Pingback: Business Analyst Resource: Bridging the Gap blog - Brian Shea

  11. Sajan Rajah

    Hi Tony,
    Great article!
    By chance, I happen to use a similar approach for marking the post-v1.00 drafts. My preferred approach is:
    Document title v1.00 yyyymmmdd – being the initial approved document;
    Document title v1.01 draft01sr yyyymmmdd – 1st draft improvement to v1.00 with author’s initial
    Document title v1.01 draft02ab yyyymmmdd – self explanatory
    Document title v1.01 draft03sr yyyymmmdd
    Document title v1.01 yyyymmmdd – 2nd approved release.

    This approach gives multiple drafts from various contributors, and their initials help all identify who just made the latest changes even if several changes are done the same day.

    I like the idea of using WIP as a suffix. I’ll see how it works out for me. :)

    Cheers!

    Reply
  12. Simon

    I like your solution, but it only seems to half-solve the problem. At the start, you point out that the V1.0, V1.1, V2.0 system makes it unclear whether V1.1 is a minor revision of V1.0, or a draft for V2.0. This is exactly the problem I have with one of my documents where we have both types of change (it’s a weekly report file, so each week I have new data and a new major version number, but if I make any minor change to that week’s report, I want to keep it with the same main version number) and I’ve just been handed the V1.0 system to use.

    Your solution is nice that it makes sure that drafts have the same version number as the final copy for which they are drafts, which I like. But you don’t suggest what I do when I later make a minor correction to that version (ie if V2.1 is a minor correction to V2.0, and not a draft for V3.0).

    Also, using the words Issue and Draft/Final make the name quite long.

    What about something like below, where I have two drafts before a final version, and then a second final version which is a minor correction to the first. And then a draft before the final version the following week:
    V01_D01
    V01_D02
    V01_F01
    V01_F02
    V02_D01
    V02_F01
    Where “D” means Draft, and “F” means Final. And “V” tends to indicate “Version” to people so that even if they don’t know what the code means, they can guess it’s a version number. Bonus that D comes before F in the alphabet so it even saves all my drafts before my finals which is handy.

    This is like yours, just uses “V” instead of “Issue ” and “D”/”F” instead of ” Draft “/” Final ” to keep my filename a bit shorter. And then after a final version, if I make a further final version (ie a minor revision to a final document), I can make it clear it’s F02 which replaces F01, whereas if I am making a draft for a new version, the major version number goes up and then I have D01 for draft.

    Reply
    1. Tony Heap

      Hi Simon,

      In my numbering scheme, there is no concept of a “minor correction”. If there is a need to change Issue 2 Final, I would draft the change as Issue 3 Draft A, get it approved and then issue it (approved) as Issue 3 Final. Version numbers are free, after all, and it keeps the approach simple! In your situation, it sounds like you have a very specific need to have one new version number per week, so I guess you need to extend the method.

      In terms of abbreviations, I try to avoid them because they assume everyone knows what they mean. If your audience is small, and you can guarantee they will understand what “V01_F02” means then that isn’t a problem. But if your audience is wide, you might want to think twice about abbreviating. As with versions numbers, alphanumeric characters in filenames are free, you can use as many as you want!

      At the end of the day, I would say do what works for your particular situation.

      Reply
      1. Simon

        Thanks :-) I’ll consider something like V01_Final01 since you’re right that D/F might not be very clear although the V would be clear in my case. But yes, because of my specific reports where I get more than one Final version of report based on only one Final dataset, I get value from having V01_Final02 instead of V02_Final, since then I can keep the Version numbers increasing only when the main dataset changes.

        Useful, thanks :-)

        Reply
  13. Sarah

    Tony- this is so useful, thank you. I have similarly always dislikes uing 1.1, 1.2 etc too but had never thought to break away from the “rules” and try something different- but your case above has fully persuaded me. I do a lot of work where I am changing Standards of Performance for service businesses and I am sure this method will be so much easier and straightforward for everyone involved to follow.

    Off to try it right away!

    Many thanks- Sarah

    Reply
  14. Luke

    One thing I like in particular about your approach is using words instead of just a numerical code. As a programmer I appreciate being able to read something I’ve never seen, and understand it. Usually this is variables and function names but I’m always extending everything I learn about code into other realms.

    Why use a numerical code which requires some special knowledge to understand?

    However, I see no reason to switch to letters when marking drafts. A combination of a number plus a “document state” tells the story. This would lead to

    failover_procedures_v_2.draft16

    However, looking at that I see another problem is that it even though I understand from your nomenclature that this is supposed to represent “before” 2.final, the fact that the word “draft” comes after the “2” makes it seem like I’m building on top of 2.

    Not sure how to solve this.

    Reply
    1. Tony Heap Post author

      Hi Luke,

      One of the reasons for using letters instead of numbers is to combat the problem you describe – it reduces the potential for confusion between e.g. “Issue 2 Draft 3” and the more traditional “Version 2.3”. But as you say, it’s not perfect. Unless you want to call it “Draft 3 Towards Issue 2” – but that’s a bit too wordy!

      Reply
    1. Tony Heap Post author

      Not really – semvar is all about version control of software, in particular software with a public API. Whereas my version numbering scheme relates to documentation.

      Reply
  15. Pingback: You don't need productivity hacks: here's how to get things done.

  16. Jane Blacksmith

    Thank you for your numbering scheme. I’m a graphic artist and an animator. Changes and tweaking are a given and they are myriad. I can’t seem to come up with a numbering system that doesn’t boggle my mind after a while and leave me completely flummoxed. I like your system. Thanks again.

    Reply
  17. Craig

    Very, very helpful. When working on a shared drive, I notice that people can intuitively process your suggestion. I’ve noticed that most people try to do it, but because the syntax isn’t documented and standardized, they waffle and we wind up with 1.0 Final, 1.0 New Final, 1.0 Final Final.

    The key question for version 1.1 is whether it will be released. Every change should (I say must) be approved, otherwise we are accumulating a series of unapproved changes for some future approval and release. If one does the latter, then 1.1 cannot be released and it is considered an internal interim version. To do this well requires a change/release/document control log (whatever we want to call it).

    Reply
  18. Josephine

    This is a great thread and very timely as I’m about to write a short document around file and folder taxonomy for a PMO team. I’ve always been a bit nerdy about file naming protocols as it drives me to distraction when I can’t find a document – bit like looking through an untidy draw for an elusive item. Well named documents are a cinch to find and I’m well in favour of the Tony’s suggestions above but would also include a date indicator using the YYYYMMDD format to ensure that all docs are in a chronological order. I also use words rather than letters i.e DRAFT, BASELINED etc for clarity. My preference for revisions to a baselined document is to the use the current version i.e. v1.0 and add minor increments 1.1, 1.2 etc until all changes approved and then baseline it at the next major increment i.e. v2.0. There’s an excellent example of document naming protocols applied specificallly to an organisaiont (a uni in this case) which I thought worth sharing: http://www.ed.ac.uk/records-management/records-management/staff-guidance/electronic-records/naming-conventions.

    Reply
  19. Chris

    This thread of full of useful contributions that complement the OP, so thanks to each of you. I’m about to start a business and want to set practical guidelines for our new, pristine online document store (with built in version control). In previous roles I’ve had to grudgingly accept that different situations require different naming conventions, but those apparently choosing the convention seemed to make it up as they went along! Our folder structure will emerge organically, so I’m considering setting a rule that says sub-folders with CAPITALISED names should contain a file with the naming conventions for that branch, whereas folders in Sentence Case should inherit guidelines from the parent (or grandparent) folder. I’ll suggest they read this post and follow Josephine’s link to the excellent guidelines written by Anne Thompson of the University of Edinburgh. I wonder whether this will be empowering … or perhaps just lead to chaos?!

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *