In all software engineering projects, documentation is critical.

This is the first of two¹ posts where I discuss my experiences and insights about project documentation – particularly how versions of documents are recorded – offering some simple suggestions for improvements that you might not yet have considered.

Documentation serves to record things like why you're doing what you're doing, how you are doing it and how to pick up from where you left off. I've seen more than a few projects fall into big trouble – or cause serious post-implementation support problems – because of lax attitudes to documentation rigour.

Most often, documentation best serves a project if the following is understood before-hand:

• What documents will be produced;
• When will they be produced;
• What benefit will they have;
• Who will review and/or approve them;
• What are the pre-requisites for each.

Until there has been enough exposure to the expected documents, projects tend to worry about these matters and the impacts they will have on the success of each project².

One of the core Problem(s): document versioning

The aspect of documentation that – to my view – causes the biggest problems is versioning of the documents. Versioning of technical files, like source code files, seems not to be a challenge. For the technical staff, it's somewhat ingrained. For the non-technical staff, it's not massively important.

If you agree with me, however, that the following two assumptions are correct, then we need to be as rigorous with our document versioning as we are with our source code files:

1. A project's documentation is as important to the success of the project as all other artefacts, like source code.
2. Project documentation doesn't magically appear out of nowhere: it's developed iteratively just like any other aspect of a successful project.

Traditionally, I have required the same revisioning regime for our documents as for our code files. However, not all documentation can be maintained in this way, and not all projects operate in this way (even if it's technically feasible).

Very often, revision control of documents is done in an ad-hoc manner. Also, the tools being used are not designed for the task (e.g. going back through old e-mails), are not up to the task (e.g. versioning by giving files different names) or don't integrate well with the revisioning tools used by the rest of the project (e.g. Microsoft SharePoint – unless, of course, you're using SharePoint for versioning of the rest of the project, in which case I suggest you stop reading this: your problems lie elsewhere…).

And then there's the problem of consistency: in many environments, documents are versioned using the scheme that the author at that time thinks is appropriate. When you have many authors, each using a different scheme, each deciding on a case-by-case basis what his/her scheme is, you can get the following:

• 0.1
• DRAFT 0.2
• 0.5
• FINAL 1.0
• FINAL Updated
• FINAL DRAFT – For approval
• FINAL FINAL 0.9

… which might describe the progression of just one document!

And then there's the problem of internal consistency: I've often seen a single document with up to 3 different versions expressed in it: in the document's file name, in the title page of the document, and in the footer (or header, or both) of each page of the document. There are many who have had perfectly good documents rejected by me because they neglected to update the version information in all places in the document.

In part two of this two-parter, I'll set out a small set of guidelines that would address the significant issues around document versioning. Once I have it published, I'll update this post with a link to it.

Update: it's here.

---