- The Pathology of Poor Planning
- 2 The Vision Document
- 3 The Functional Specification
- 4 Recognizing a Bad Plan
- 5 Excellence Is Attainable
- 6 A Software Blueprint
This chapter is from the book
This chapter is from the book
This chapter is from the book
2.3 The Functional Specification
After the Vision Document is approved, effort typically shifts to production of the Functional Specification. Some companies create separate marketing and technical requirements documents, but however it is packaged we will call it a Functional Specification here to avoid getting lost in terminology.
Flashback—VB Database Class
I have taught a class on Visual Basic database programming for many years. As part of that class, my students complete a personal class project. Their first assignment is to produce a simple one-page Vision Document/Functional Specification of their project. I tell them to simply explain in plain English what their planned programs will do. You'd think it would be easy points.
Despite the apparent simplicity of the assignment, I get a tremendous variety in content, most of which is not at all useful. Their planning documents are littered with sparse, overly general, unnecessarily detailed, or meaningless boilerplate. Although I expressly tell them not to dwell on implementation aspects such as database structure because that is documented in the next lesson, most do so anyway. Most of the students do not communicate effectively and do not seem to consider the needs of the reader.
At one point I became so frustrated that I considered discontinuing this assignment. Then I decided that the fact that students have so many problems with it is the best reason to continue to assign it. Usually out of a class of 24, there will be two or three reasonably clear specifications that actually do give the reader some useful insight into what their project will do. I typically read one or two of those to illustrate an effective specification and point out what the student did right.
The Functional Specification is the cornerstone of software planning. It embodies all of the business requirements, software requirements, and product specifications. The intent is to provide a complete, self-contained master plan of what will be produced. Normally, it is hoped that by the time this document is complete, all questions have been answered and the solution has been fully designed on paper. With the Functional Specification in hand, many managers and planners feel that they should be able to hand it to any development team and lock them in isolation until the system is ready for deployment.
We often spend as much time preparing this document as we do developing the application it represents. This entails a tremendous expenditure of time, effort, and resources. The amazing thing is that in the end, no working code is actually produced. That is not to say it has no value, but it will not process one transaction, send one byte of data to a hardware controller, or accept one character of user input.
Certainly one would argue that the Functional Specification pays for itself ten times over by preventing errors and inefficiency during development. This is the basic assumption implicit in most planning literature. That may be true when the Functional Specification is appropriate for the project it represents. However, all of the reported benefits of a Functional Specification do not normally consider its quality. They do not consider the cost and risk of a poor Functional Specification.
The reality is that many Functional Specifications are quite poor and fail to produce a fraction of their expected benefits. In practice, we are fortunate when developers can find anything of value in a Functional Specification. Often it is highly debatable as to whether these documents are worth the effort that was put into them.
At that point in their studies, my students should not be expected to know how to write an effective planning document. However, the same degree of variation in content and quality exists in most commercial Functional Specifications. These documents come from professionals who should be skilled in this work. Even though the real-world specifications get bigger and take longer to produce, they don't necessarily get better. If anything, the authors of commercial specifications have even less ability to produce a useful specification than my students, relative to the scope of their tasks.
Most commercial-quality specifications suffer from the same fundamental problems as the student specifications, except on a larger scale. They are verbose and complex, they lack cohesiveness, and they include a great deal of extraneous information. If anything, the problems are magnified because of the greater level of scope, detail, and interdependency required in a commercial application.
Consequently, as with the Vision Document, the Functional Specification does not get utilized as effectively as the planners might imagine or hope. In far too many projects, the developers barely look at the specification. When they do consult it, they typically absorb only the few discrete sections that are useful and then ignore the rest. Usually the only parts of the specification that have much value are the screen mock-ups or prototypes. Even these mock-ups are often created without considering the needs of the developers. The rest of the information is frequently too sparse, disorganized, inconsistent, and incomplete to be of much value.
Developers typically take what they can from the specification, and then go back to the client experts for additional information. From the developer's perspective, this is far more efficient and accurate then trying to glean more information from the specification. From the management and client perspectives, this is frustrating and redundant. Even worse, it opens the possibility of scope creep.
The term scope creep describes the phenomenon in which features are added or changed after the specification is finalized so that they increase the time required to deliver the product.
Planners probably spent many months working on the Functional Specification in an effort to anticipate and provide the developers with all the information they need to produce the product. They are understandably frustrated and bewildered when the developers never seem to use it effectively. Management concludes that greater control is needed to force those developers to adhere more rigidly to the specification.
As with the Vision Document, the reason that these documents are so out of touch with the needs of development is that the planners probably never actually asked their developers in advance what they need and how to present it. Developers were handed a document that did not seem to be prepared specifically for them. And in truth it probably was not. It was probably prepared first and foremost to satisfy the very different expectations of management and client.
What we end up with is a highly inefficient planning process that devours resources and doesn't meet the needs of the developers in the end. The best way to produce an effective specification that serves developers is to go direct to blueprint9 and use the Software Blueprinter application10 or something like it to produce a developer-oriented specification as the planning process progresses.