If you agree that documents should be passed around as an address or link – rather than as an attachment – and that older versions should not be in the same directory as the current version, then this recommendation becomes logical: Don't permit the names of the files that contain document to express any kind of version information.

If, say, you pass around a link to the document BusinessRequirements_v0.2.odt, then as soon as v0.3 is announced, that link will either be pointing to the wrong document, or to an address that no longer exists. The latter can be annoying for the person trying to review the document, but the former could cause more serious problems, as the wrong version will be accessed.

Similarly, if you operate the rule of keeping only one version of a document in the directory it is to be found, then putting version information in the file name doesn't make a great deal of sense, and may cause confusion.

If, however, you mandate that document file names¹ should not make reference to the document's version, then you derive the following 3 benefits:

1. All e-mails and other resources that provide the document's address will link to the correct version of the document at all times.
2. Visitors to the document's official directory will be without doubt that the only document with BusinessRequirements in its file name is the current version of the business requirements document, especially as it's called BusinessRequirements.odt.
3. The maintainer of the document has now one location fewer in which to update the document's version number, reducing yet more the risk of internal inconsistency.

A project should appoint one member to be a librarian. This person would set up the document repository and be a document reviewer, looking for compliance to the project-specific rules on document versioning. If this person has early visibility of the documents-in-draft, then compliance advice can be given early, which will help keeping things in line.

This wouldn't be a full-time role, of course, but it should be filled by someone on the project. That way, you have someone who's close to the work, and its goals, rather than someone who's sole job is to declare rules for others to follow.

One of the hardest things to do for someone working in the earliest stages of a project is to start preparing a mandatory document. "Is there a template?", "Can I use a previous version?", "Where will I put it?", "Who will review and approve?", "What's the correct way of passing this around?", "How long will this take to prepare, and how much of that time will be spent on document compliance?"

A project office worth its name should have all these answers available for you in an easy-to-read and easy-to-follow format. The goal around a document maintenance frameworks should be two-fold:

• It should be easy to do things right; and
• it should be hard to do things wrong.

As I said in part 1, traditionally I have required the same revisioning regime for our documents as for our code files. Consequently, I have always maintained technical documents in the project's revision control system, and I have required my teams to do the same.

The primary reason for this is straight-forward: as we create project labels or tags declaring that our development has reached specific milestones, it's a good idea to make available to a reviewer the documentation that is associated with that specific version of the deliverable.

For example, if the label implements the requirements as they were agreed in March, the delivery should be assessed against that version of the requirements document, and not the version that was agreed at the end of May and not yet sent to the development team. If the correct version of the requirements document forms part of the label, then there is less difficulty in validating the delivery.

As well as the above, excellent, reason, consider how maintaining your project documents alongside your technical files – in a dedicated revision control system like, for example, subversion, git, TFS (if you insist!) – can help with my guidelines.

1. By using a revision control system, you can rely on its scheme for incrementing revisions. You don't have to devise one yourself. Also, you could go further and using tagging or labeling to mark files as DRAFT, FOR APPROVAL and COMPLETE.

2. Many revision control systems have a feature called keyword expansion. This will allow the revision control system to update files with specific information, including the document's revision within the system. If your document has a field that uses the relevant keyword, the revision control system will update it automatically, removing the need for the document's author to do this.

   Now, the document's author or maintainer doesn't have to update the revision number anywhere in the document.

   The only problem with this is that files that use compression as part of its format (e.g. modern Microsoft Word XML files or ODF) aren't accessible to this feature. Nor are encrypted files. It works great, though, with the older Microsoft Word *.doc formats².

3. All modern revision control systems are network-capable, and allow files maintained within them to be referred to by a simple URL (TFS excepted; those URLs are a nightmare. Even worse than SharePoint!). If you are liberal with your document-access policies (e.g. everyone has read-only access), then everyone will become used to seeing documents being passed as links that all look the same as links to tags and other resources in the revision control system.
4. A revision control system doesn't help with the embedding of documents. However, it will make accessing those documents easier if you use links.
5. The revision control system will automatically hide older versions of documents. These older versions will always be available, though, through the revision control system's interface.
6. The value of a revision control system would be lost if you changed the name of a file every time you updated it. In fact, keeping the file's name the same for as long as it's relevant will allow you to derive the full benefits of using a proper revision control system.
7. The job of a project librarian is made easier as there are fewer locations to keep an eye on. Also, as some tasks can be performed automatically by the revision control system, the librarian's reviews will consequently be shorter.
8. A revision control system will help greatly in making it easy to do things right and hard to do things wrong, but will give little help in developing a framework that you might want to use for that.

And, that's it.

Thank you for reading. If you think any of my guidelines is flawed, please let me know. My contact details are at the bottom of this page. Also, if you want me to clarify anything, let me know.

At some time in the future, I might address some of the other problems with project files and artefacts, like…

• Spaces and other special characters in file names.
• Formatting and how stylesheets help impart the information.
• Addressing the "I just don't see the value of doing this," and other misconceptions around documentation.
• Why the name of a file doesn't necessarily indicate what's in the file, and the wider consideration that we shouldn't confuse a document and the computer file that contains that document.