Paper Monsters

February 2002

Mention the word "documentation" in relation to software projects and you can see the fear in the faces of the most experienced programmers. This apprehension probably derives from years of experience of being presented with poorly thought out, ambiguous and badly written documents and the inevitable consequence of fraught software development projects.

This article is aimed at those who write the all important initial documentation, the clients of software development projects, and presents the developers' perspective. Having worked as a programmer for many years and having seen many reams of documentation some good, most instantly forgettable and some downright ugly; I can speak with experience. I make no distinction between projects developed by an organisation's internal systems department and projects developed by external suppliers, though for what its worth I think that producing documentation for internal projects can be even more difficult than external ones.

Most software projects start with one or more documents. Sometimes small, sometimes extending to many volumes. In principle these documents should specify what the system is for, from a purely business perspective, what business processes need to be supported and finally in more or less detail, how the system will actually work. These documents are often intended for different audiences, including the people who are going to write the system as well as the people who, directly or indirectly are going to pay for it. These documents may range from well written, comprehensible tracts that explain some aspect of the system in terms anyone can understand to appendices of highly complex runes which are totally inaccessible to anyone not intimate with the rules and conventions of technical documentation. Often the technical part of a specification provides essential details to guide the developer towards the correct solution.

From my personal perspective the most important of these documents is the one that actually tells you what the thing is for. It may sound obvious but writing down what you want to achieve, in a language that everyone from the chief executive to junior developer can understand, makes everything that follows more likely to succeed. There may well be a need to develop more detailed documentation for some or all of the system but without the high level overview how is anyone supposed to know how it all fits together?

The sort of project documentation which makes my heart sink skips any sort of introduction or background and wades straight into the low level detail of screen shots and field sizes. The reason these documents alarm me is that within all the detail about screen layouts and report columns there will often be a short paragraph that says something like '... and the system will integrate with accounts'. This sort of throwaway remark almost always hides a multitude of sins. These include why? , 'do accounts want to be integrated?', 'what are they going to be integrated with?' and does anyone in accounts know this? My experience is that whoever wrote the document either didn't know or understand what was actually required, didn't ask the people who did know or didn't have the seniority to get the people who did know to tell him or her. Either way, it would be nice to have a little more information before anyone actually starts building the system. The well intentioned motivation behind this type of document is generally to make sure that nothing gets missed and no detail, however trivial is overlooked. Sadly the fairly inevitable result is that anyone reading it gets so bogged down in the mountain of paper that if some important aspect of the system has been missed there is almost no chance of it being spotted until its too late.

A variation on this theme is the 'helpful' document. The author, using a technical knowledge which is not necessarily as extensive as he might like to think, decides to 'help' the developer by telling them how to do their job rather than what the job actually is. Fortunately this style often betrays itself by using technical terms and jargon when straightforward English would have been clearer and more useful to all concerned.

The usual end result of this sort of document, which can read like an over prescriptive Delia recipe, is that when the development team get to the final page, they find that some important ingredient was incorrectly specified or simply missed out altogether. At best the job takes longer than expected and at worst results in tears and acrimony on all sides.

Given that most developers are perfectly capable of misunderstanding, misinterpreting or simply ignoring parts of the requirements that they don't like, there seems little point in colluding with this by not providing the right information in the first place.

My final thoughts are that whoever writes your specification documents, be they a user, business analyst, developer or simply someone who was in the wrong place at the wrong time, do get them checked. It may well be that that all the beautiful flow diagrams, relationship models and complex algorithms are essential for a full understanding of the project. But if it doesn't say, in reasonably clear English, what the whole thing is actually for, then odds are sooner or later there will be tears and not just those of the programmer.