Pitfall: Allowing the specification to drift or change without agreement

[From Pitfalls of Modern Software Engineering by Bruce F. Webster (forthcoming)]

Categories: managerial

Let’s start by freely acknowledging that, with rare exceptions, software of any complexity changes between original specification and actual delivery. This is to be expected, and to a certain extent encouraged, when the changes represent a refinement of our understanding of the problem domain and the required solutions. Hence Brooks’ assertion that we must be prepared to “throw one away” — we just don’t know for sure what we’ll need to build and how to build it until we’ve built one. One of the advantages of modern technologies and methodologies is that such changes and adaptations can often be made readily and at lower cost in time and risk than for earlier development approaches.

Let’s also acknowledge that, given the time required to deliver a significant piece of software, customer requirements, technical expectations, and market conditions may change dramatically between the time a project is specified and when it is delivered. As John Donovan noted many years ago, the distance between the leading edge of technology and the trailing edge appears to be constantly shrinking. You may need to redirect or revamp projects as they go along in order to respond to such shifts.

But that’s not what this pitfall is about. This pitfall is about specifications that aren’t nailed down, or that aren’t firmly specified at all. A given feature or aspect of the project is discussed (or maybe it isn’t). As time goes on, the person(s) implementing it have one idea as to what it means or may even have new and improved ideas for it. Those not implementing it may be assuming something quite different from what is being written. Those not involved—including, and especially, upper management—may have quite a different (and erroneous) idea of what the feature will be. And customer expectations may be something else again. When the time comes for feature completion, code integration, project review, or customer acceptance, all hell breaks loose.

Symptoms

Lack of specification documentation. Engineers showing off “new features.” Mismatched subsystems. Constant delays in completing given features.

Consequences

Schedule slips due to ever-changing specification and integration problems. Lack of management, marketing, or customer acceptance of the delivered project.

Detection

First, see whether you can put your hands on a detailed list of features. If no such list exists or if it is incomplete or vague, then you have problems.

Second, see whether you can find a detailed description for each feature, including clear information about what it will not do. Missing or incomplete information is another danger sign.

Third, compare the specification against what is actually being implemented. Variations are yet another indication of trouble.

Fourth, propose a change in specification and see what is the process for making it. The more informal and undocumented the process, the greater the danger of this pitfall.

Extraction

The Detection exercise should give you a good idea about your current state and how to get out of it: Produce the documents described and then use them as a hard spec for the project.

A second (not necessarily exclusive) approach is to write a complete user’s manual for the project and let that be the final specification. This is what we did many years ago at Pages Software: the user documentation, complete with screen shots, was printed a full nine months before the product was released. The president and CEO of Pages gave a copy to every engineer and said, “Here’s the final specification.” It saved all of us from the temptation of making further changes.

Prevention

Establish a process to create, review, modify, and enforce the specification. This is, in effect, the documentation of the design phase of your methodology. This process won’t be easy or popular, but it will pay off significantly in the long run.

This is such an obvious and well-known pitfall that I’m almost embarrassed to include it here. But it is still so common that I must.

References

Webster, from Pitfalls of Object-Oriented Development (1995).

About the Author: bfwebster

Webster is Principal and Founder at at Bruce F. Webster & Associates, as well as an Adjunct Professor for the BYU Computer Science Department. He works with organizations to help them with troubled or failed information technology (IT) projects. He has also worked in several dozen legal cases as a consultant and as a testifying expert, both in the United States and Japan. He can be reached at 303.502.4141 or at bwebster@bfwa.com.