NOTE: This article may be reproduced and circulated freely, as long as the copyright credit is included.
"Just because you have a detailed requirements specification that has been
reviewed and signed off, that doesn't mean that the development team will
read it, or if they do, that they will understand it, or if they do,
that they will choose to work to the specification."
- Scott W. Ambler: "Agile Documentation Strategies", Dr. Dobb's Journal, March, 2007
Don't worry—Mr. Ambler didn't mean for us to take that observation as serious counsel. He put it forth as one of five1 "myths and misconceptions . . . potential misunderstandings about documentation that have seeped into traditional thinking." - p. 67.
If such muddled thinking is really becoming a tradition, then our projects are in even more trouble than we had thought.
We've reluctantly conceded that some fad methodologists are discouraging not only the preparation of rigorous detailed requirements, but also the need for most kinds of documentation. We won't argue those issues further here.
However, it hadn't occurred to many knowledgeable practitioners that even when a project does manage to produce a solid set of requirements documentation our programmers might still ignore it. That's the situation that concerned Mr. Ambler in the above quotation.
What if the developers don't understand the specifications?
Requirements documentation (also called an external design or functional specification)2 has two audiences:
Reader feedback and further clarification, April, 2007
Most readers who responded to this article last month expressed agreement and frustration, and were glad to see the issue raised. One reported on a fiasco project where requirements had been documented but then largely ignored.
The three people who strongly disagreed cited experiences with projects where the requirements couldn't be known in advance and had to be elicited incrementally as the software was developed. But some of the examples they offered didn't address requirements at all, but rather issues like programming standards and internal design.
It may be helpful to clarify the following essential points:
Both audiences must understand the entire specification in exactly the same way. If either audience doesn't understand any detail or finds the specification incomplete or ambiguous in any way, then they are obliged to raise appropriate questions. At that point the author of the specifications, usually a systems analyst, is obliged to revise the material to plug any hole and resolve any ambiguity.
That process may require several iterations, generating impatience among the sponsoring users, the development team, or both. Nevertheless experience has repeatedly shown that the time spent in getting the specifications right is much less than the time to make revisions during testing and implementation. (This is especially critical when a packaged application program product is to be used, since a seemingly minor requirements change may invalidate the choice of product.)
Getting the requirements right doesn't mean that they're frozen for the remainder of the project. During the course of a major project a changing business environment or just further insights may well suggest or require changes.
That one's easy. What do you do with any employee who defies his or her superior or ignores any assignment?
The term that descibes such behavior is "insubordination". Nearly all organizations consider flagrant insubordination, after a warning or two, a firing offense, even if the employee is shielded by union, tenure, or civil service protections.
In a professional environment a project team member will have ample opportunity to express his or her reservations about an assignment and to propose modifications to the assignment. In an extreme case a team member might decline an assignment that violates professional or personal ethics. But once the project manager and the team member reach agreement and the team member accepts the assignment, there is a firm contract. The developers are expected to deliver a system that conforms to the (possibly amended) requirements. Any deviation is considered a bug (or "defect") which the developers are obliged to correct.
2 — Of course, we're talking here mainly about bona fide functional requirements, i.e. what the proposed system will do, not constraints on the implementation, called non-functional requirements by some. Deliberately violating development standards is a serious offense, but disregarding the external specification is more damaging in the short term.
Last modified March 16, 2007
Return to IDI home page