However, he says, they weren't the classic use case. "All they contained were example screen shots and comments about the content of the screens. Business rules were sometimes included, sometimes not. And absolutely no standards were applied." For example, a simple-sounding requirement for fields to be "numeric only" could be interpreted in several ways. One developer displayed an error message in a dialogue box; another cleared the field if alpha characters were typed; yet another disabled all keys except numbers when the user was on that field. All three met the "requirement", and all were included in the same application. "Talk about end-user confusion factor!" Damon says.

Beware, however, of requirements documents with multiple purposes. It's easy for these to become corporate documents rather than product specifications — which may have conflicting roles. Typically, a contract with outside software providers has customers sign off on software requirements before implementation begins. As one consultant pointed out, because the stakeholders (among them the CIO) need this to happen as soon as possible, the signed requirements are written to be suitable for customers and contracts, not for developers and testers. According to the consultant from Latvia, later in the process, developers and testers find the requirements unspecific and ambiguous, and they don't reflect deep knowledge of the business. The developers discover that the requirements aren't technically achievable and are barely testable.

Sometimes, once the developers are under way, they'll learn the requirements are simply wrong. And, he says, "While that's the signed document (and the requirements phase is marked as 100 percent complete in a master schedule), it is not going to be changed any more, no matter how poor it is."

One developer I met online, Malcolm, cynically observed that, "What happens is that the specification looks superficially complete, but in fact contains hidden inconsistencies, glossing over, omissions or impossible conditions. The document, if it is binding, then becomes an impediment to the project, plus a source of irritation."

One solution may be to rely more on business goals than exacting technical details. Gottesdiener recommends that companies break out of the "system shall . . . " paradigm for specifying requirements. "We've got to stop relying on long, tedious textual requirements documents. Insist on smarter documentation," she says. Instead, rely on models built in collaboration with business folks, such as requirements workshops.

According to Gottesdiener, "Customers 'playing around' with their needs with cheap, fast and low-fidelity prototypes facilitates the meta-pattern underlying requirements development: evolution. Evolution is chaos, with feedback."

One developer suspects the preference for more-or-less detail may depend on the nature of the environment. "If you're in a situation where there is a high level of trust, a loose expression of requirements allows the team (including the customer or nearest surrogate) to zero in on the real requirements through some amount of iteration." In his view, the need for excruciating detail is characteristic of an environment in which the best political defence was to show that the code did what the requirements said — even if the best commercial value was otherwise. "To do that, the requirements must be explicitly definitive." If you're unsure if your development department has achieved that measure of trust, this agile developer suggests that "requirements should begin with some kind of preamble giving intention. Sometimes, two different implementations might completely satisfy the raw requirements, but one might be ever so much more idiomatic to the underlying business motivation and thus more maintainable and extensible."

So, how do you know how much detail is "enough" for a software specification? There probably isn't a single right answer. The savvy manager will recognize or create an appropriate corporate culture — which may mean asking developers and testers, during job interviews: "How detailed do you prefer application requirements to be?" Because if a CIO thinks the requirements documentation should be one way and the development team wants it another way, friction is inevitable.

It's bad enough to deal with developers who can be counted on to quibble over the amount of detail put into the software requirements. But now we get to their major concern: the perception that CIOs are poor at dealing with changing requirements.