Tuesday, March 16, 2010

Why you should use a change log in your documentation

There has been a functional specification document going to and fro between us, the clients, and them, the vendor/consultants, for a few weeks now. Version 6 was released this morning. Including the files that have been submitted with annotations by our marketing team that makes 10 versions to review altogether.

The annotated responses are fairly easy to review as the annotations (marked comments) stand out from the document text. So, I just flick forward to a comment, read it and move on to the next one.

However, the official versions which are then submitted in response by the consultants, are not annotated and do not include a change log.

We're talking about a 53 page document. I don't have time to read the same 53 pages six times.

When I produce such documentation I always include a Document or Revision History table at the start. It looks a bit like this:


Version
Date
Author(s)
Notes
0
12/03/2010
Lindsey Buckle
Initial Version
1
15/03/2010
Lindsey Buckle 
Draft following technical discussion. 
Updated table p8: added 'File' column


This way, whoever is reviewing the document knows that the only thing that has changed is on page 8 and they're directed to it. They can flick forward to page 8, check the table with its new column and decide whether to approve the document. Much quicker than scanning every page of a 53 page document trying to figure out what has and hasn't changed.

What do you do? Do you include a change log? If so, what details do you add? Let me know in the comments.

1 comment:

  1. I use something very similar, no version number though just dates. I guess there's the remote chance that two people could update the document on the same day ... but I think the key is the notes section, actually describing (briefly) what you changed is a help! Unfortunately that takes a bit of discipline and can sometimes be poorly done, e.g. by writing Notes: "Made Changes".

    ReplyDelete