Obsolete Documents

By Matt Stephens
March 3, 2002

It's a fact of life that requirements change during the course of a project. This is especially true with "Internet-time" projects instigated by Product Steering Committees and driven by vague high-level "visions" of the eventual product functionality.

The same is less true (but still a factor) with formal projects being run by Government departments, blue-chip companies and so on - for example a taxation system, where the same rules and procedures were probably still valid 20 years ago.

However at both extremes, it is vital to ensure that everyone is using the most up-to-date documentation. For "Internet-time" projects, it is vital because the requirements will change every time your dotcom CTO wakes up with another crazy new idea. For more formal projects, it is vital because the project is likely to be much larger in scale, with requirements, functional specs, architecture and design specs running into hundreds of pages.

Even if the requirements or the design don't change very often, the number of people involved means that fifty people could be working from an obsolete specification without even realising it. They are creating code that is obsolete before it has flickered onto their screen.

It happens. Sometimes it's a genuine mistake - people just didn't realise the specs had changed - other times, the reason must be unavoidably attributed to the team's apathy in getting the latest spec, even after being told that it had changed.

Most often, it's a mixture of the two - the team is simply too busy to think about such "administrative" tasks as tracking down the latest changes and analysing how it differs from what has already been implanted in their minds or in their code.

It is human nature to regard something written down as a contract, or even sacrosanct. The age of a written document also seems to contribute to its perceived importance - the older a document is, the more sacred and infallible it must be. Amazingly, this perception even applies to project plans and out-of-date architecture diagrams.

This is why it is so important to keep updating your project plan, your use cases, your business processes, your design documentation - everything.

The Extreme Programming (XP) solution is to do away with documentation altogether. Unfortunately this means losing all the advantages that documentation brings us, such as lack of confusion. I would suggest that some very simple, practical and much less drastic measures can be taken to virtually eradicate this sort of confusion in your organisation. And you get to keep your documentation, too!

The first, most important, and probably most obvious step is to make sure that everyone is accessing the project documents from the same centralised location - therefore they are always looking at the most relevant and up-to-date version.

If somebody really wants to look at a two-week-old (i.e. ancient) plan, then let your version control system (VCS) handle it.

In other words, make it more straightforward and intuitive to access the most up-to-date version than to access an older, less accurate version.

In many cases, the natural thing to do is take a local copy of a document, store it on your PC and read that version. If that happens, it doesn't matter how often you update the document, numerous prior versions are still being read on various PCs throughout your organisation. Each person is looking at a slightly different snapshot of history.

This problem exists because it is easier and more intuitive to look at their local, older version than to go and find the most up-to-date version buried away on the network. They probably don't even know that a newer version exists.

I worked on one project where the project manager asked everyone to send an email around every time they changed something. As you can probably imagine (or may have experienced), this just isn't practical. The team quickly became buried under a pile of annoying emails. What made matters worse was that the manager didn't recognise this fact, and refused to adapt to the reality of the situation.

This was doubly annoying, as the solution really is quite simple and straightforward...

The Solution

The solution is simple, but you really do have to work at it, to ensure that everyone is working from the same version of everything. For starters, make it EASY to access the latest versions of all documents.

The easiest and most effective way to do this is to set up a project intra- (or extra-) net from day one, from where all documents can be accessed with a single click (not necessarily HTML documents - remember Word, Project, Acrobat etc are all readable from a browser window).

Remember also that CASE tools such as Rational Rose and Select can also publish the entire object model to a project web. An added advantage here is that only the people who are actively updating the object model need an exorbitantly priced Rose license.

Next, trek round to everyone's PC and add a consistently named shortcut which points to the project URL. If the project website consists solely of a collection of static documents, then you could get away with simply pointing to the machine name and directory on the network; otherwise, it doesn't take much extra work to put up an internal (to the organisation) instance of IIS, Apache or even Tomcat.

If your team are using Internet Explorer, add the URL to their Links Favourites folder, so that the link appears on their browser toolbar. They will probably be puzzled by your behaviour, and might even object to you cluttering their otherwise pristine toolbar, e.g. obscuring their access to Hotmail and MSN. Don't listen to them though. Check back occasionally to ensure that the shortcut is still there on their toolbar (perhaps a quick glance while you are talking to them at their desk, so they don't get annoyed). Make yourself the self-appointed browser toolbar police.

Then there's no excuse for them to not always be reading the most up-to-date version of everything. Because it only takes a single click to access the latest version, you have made it easier and more intuitive for everybody to do this than to hunt down and access an older version (even if it's stored locally on their PC).

Make it a part of your process!

Another important step is to review the procedure for creating and updating documents. There is little point in everyone reading from the same location if that isn't genuinely the most up-to-date version.

If there is an extra step involved after updating the document, in order to copy it to the central location, then the chances are that this step will end up being neglected - especially if several people are writing these documents, from different teams or even different buildings.

Try to streamline the process so that there are as few steps involved as possible. Again, try to make it the most natural and obvious way to do things, so that it hardly even occurs to anyone to do it differently. To achieve this, you will need to go out of your way to make the process as simple and uncomplicated as possible.

For example, depending on your setup, you might need to create some script files and copy these onto your analysts' PCs, e.g. as a shortcut on their desktop. Don't ask their permission - just turn up and announce: "Gotta install this on your PC!" If you're quick, they won't have time to think of a reason to object.

You might gain a reputation for being a "control freak", but you should thank them for the compliment. It's your job to keep the project on track, after all.

Another example is with Rational ClearCase (a version control system). ClearCase makes the on-line versions archive (or "VOB" as they like to call it) look like part of your Windows/Unix filesystem. Thus, when you create or update a document and check it in, your colleagues' browser shortcuts can point directly to the ClearCase VOB files - therefore they get the update immediately. No extra steps involved; no copying; no confusion.

Conclusion

This process might seem trivial, but it is amazing how often such common sense is neglected. The same process is equally valid for any project, regardless of its size, scope and complexity.

Of course, documentation is only one form of communication, and isn't a substitute for talking to one another. Regular update meetings, informal chats by the water cooler, telephone conversations, occasional emails - these are all just as important for keeping everyone up-to-date. However, having up-to-date documentation - and more importantly, having everyone work from the same documents - sure does make life a lot easier (particularly with large teams!)

A little extra work at the start of the project to put in place the minimal infrastructure and procedures described here, will repay hundreds of times over during the project. Because everyone is guaranteed to be "working from the same page" (literally for once!), there is much less opportunity for confusion and indirection to rear their ugly gnarled heads.

Talkback:

Post a new message

Good Idea
Dan Sterling daniel.sterling@usa.net

Clearcase through Web site
Jeremy Riley jriley30114@myway.com

Post a new message

Related Articles:

Fear of Non-Progress

Processes and the Bad Manager

<< Back to Lifecycle Articles

<< Back to Software Reality