Five Things IT Managers Should Know About Software Requirements

Some days, you wish you had telepathy. You just know that your development staff is holding back in some way, but you don’t know how to get them to communicate. Is the project in trouble, but they’re afraid to tell you?

Since your software development staff won’t tell you what they’re really thinking, I asked them to confide in us instead. I posed a single question to professional programmers and testers: If you could get your CIO to understand just one thing about software requirements, what would it be? From the answers, I collated the five things at the top of their minds. If you grok these concepts, you will win the respect and support of your programming department (prizes you’ll also earn for understanding the term "grok"), and you’ll optimize the chance of success for your next software project.

I must warn you that this will shock some developers. Most of them don’t expect you to have a clue.

1. The Inconvenient Checkbox: Understand the Role of Requirements

Many development projects are handicapped from the start. The requirements are vague and subject to interpretation, require intimate knowledge of the business to interpret correctly, and aren’t prioritized. "It’s a classic garbage-in, garbage-out situation," says James Pulley, director of professional services at PowerTest. "Poor requirements are provided to a development organization that either does not question them or receives hostile glares from the business community when clarification is sought. Items requiring insight or interpretation are interpreted one way by the requirement writer, a second way by development, possibly a third way by QA."

It’s critical to establish some sort of process for documenting software requirements—what one developer plaintively described as avoiding an ongoing guessing game. Yet, say many developers, managers often forget why they gathered the software requirements in the first place. QA tester Darrel Damon complains that some organizations act as though requirements are "an inconvenient checkbox that has to be gone through for legal purposes." In one project on which he worked, for example, management paid little attention to maintaining and updating the requirements. "It was as if the requirements checkbox had been checked, so we could move past requirements," he says. "When requirements did change, there was no formal notification to the rest of the team."

This was more than a political issue. During testing, Damon entered a defect report when he found a specific discrepancy between the application and the requirement. The business analyst said it wasn’t a defect; the application was right and the requirement document was wrong. "I argued that it was a defect regardless, because defects are not just in the app. I stood my ground and refused to close the defect. I finally got a meeting with the business owner; the requirement was right and the app was wrong. [The analyst’s] comment about it not being a defect because it was ’only a documentation issue in requirements’ spoke volumes about the value placed on requirements."

But that’s the easy item. Most developers say their CIO understands the importance of requirements. It’s what happens after that where things get ... interesting.

2. Don’t Throw It Over The Wall: The Right People Should Define the Requirements

You want software requirements that help the development staff create an application that gives the user joy. To achieve that goal, you need to get the right people into the room. Many corporations depend on a business analyst to elicit information from the user, to document it in a company-approved way, and then to throw the paperwork over the cube wall to developers who rarely (if ever) interact with the people who will be using the software.

Instead, says developer Dave Nicolette, "CIOs should use business analysts in a role more in keeping with the job title: to analyze business processes and identify opportunities for improvement. ... On software development projects, business analysts should not get between the customers and the developers. When they do, they only cause confusion."

The most important person in the requirements-gathering process is the user. Daniel Corbit, senior software engineer at CONNX Solutions, says, "Software requirements are not dictated from the top; they are gathered from the bottom. If they do not model the real-life business process of how a company does its work, then they are doomed to fail in execution. ... The key part of the equation is to carefully interview everyone who uses the tool and everyone who will be impacted by the tool to find out what it needs to do."

Put the person who will use the software in the room with the person who will create the software—which you may note is also a foundation of agile software development. Find out what the user needs to accomplish. This doesn’t necessarily mean that you need to define what each screen looks like. Carlton Nettleton, a software developer and agile coach, points out that "meeting a series of requirements is not the same thing as meeting our customer’s goals. Tell me what the customer’s goals are; even better, bring the customer in and he/she can tell me in person. We can then figure out what types of requirements are needed. Then, when we are ready to execute, let us plan around our customer’s goals, not around the requirements."

However, this isn’t a one-time visit. The stakeholders have to get and stay involved. According to Ellen Gottesdiener, principal consultant at EBG Consulting and author of The Software Requirements Memory Jogger and Requirements by Collaboration, it’s important for the CIO to ensure that technical and business communities collaborate on requirements, early and often. The classic approach is to throw a Marketing Requirements Document over the wall. Instead, she says, "A bridge must be built, to collaborate between technical and IT stakeholders. Get personally involved in this effort. Find out what works in your organization to actively and productively engage customers in requirements development."

Gottesdiener offers a real-world example. A project started, ran and failed three times. The organization tried internally once; then it outsourced it; finally it tried again internally with another IT manager. From the start, Gottesdiener explained, the business sponsor was disengaged, and participation by the users and business experts was sparse. But the solution was necessary, for both business and political reasons, so the organization decided to try again. This time, however, it conducted a retrospective to examine the project in a deep and significant way; both product and process were explored. Gottesdiener says that this time around, "They see the role management has played in colluding, not sharing information, infighting, lack of transparency. They examine the frustrations of not getting users to participate in requirements development and validation. The whole story gets put, literally, on the wall in an open manner. They decide as a team what they would need to do to be successful. It involves starting with full-time customer resource for a fixed time frame, requirements workshops, reviews, prototypes and ongoing retrospectives for each milestone. And of course, management helping them make all this happen with the right people and money, at the right time." According to Gottesdiener, the fourth time was the charm: The group delivered on time, on budget—a first for the department.

When you gather the project stakeholders, be sure to include the testing organization in the process. Performance testing expert Jim Pensyl believes strongly that testers should be involved at project kickoff. He says, "Only the testing organization can tell you if the requirements are testable. Why not then use [their] deliverables for the source of truth in status and estimation refinements?" Developer David Gelperin agrees: "Experienced testers and technical writers should be active participants in the cross-functional teams tasked with requirements development."

This is an important time to listen to the development team’s feedback. Says Jared Richardson, author of Ship it! A Practical Guide to Successful Software Projects, "If you don’t include us on the time line generation, don’t expect us to meet the time line. If the general contractor on a building project doesn’t ask the brick mason or the electrician how much time they need, how do they expect to generate a realistic schedule? They can’t. If you don’t include developers and testers when you’re generating your time lines, don’t think you’ll hit them."

Even after you get the right people to talk about what the software needs to do, you still have another hurdle to overcome: getting those requirements recorded with the right amount of detail. Where do you draw the line between micromanagement and detailed instructions?

3. Superficially Complete: Define Requirements With "Enough" Detail

Although developers uniformly insist that they want the right amount of detail in the software specifications, they often disagree on how much is "enough." One set of developers wants the minimum: a rough idea of the business problem to be solved. Anything more than that, they feel, is meddling with developer creativity, and a waste of time. One developer gave the example of "an automated system to help us do our taxes" as a fine specification.

At the other extreme is the explicit requirements document. Peter Nairn, a software tester in the United Kingdom, says he worked on one successful project that had superlative requirements documentation. In addition to a rigorous definition, Nairn says, the requirements were prioritized within the requirements document itself. "There were three levels of priority: Must, Shall and Should. Must meant the system could not go live without; Shall meant that the system would be degraded by not having it and there would be financial penalties for not meeting the requirement; and Should meant that these were nice to haves and would enhance the system." The requirement spec thus read something like this: "The system Must [1.1] have the ability to do xxx and Shall [2.3] be able to yyy and Should [3.3] be able to zzz." The numbers in square brackets referenced an appendix to the document with definitions. Explains Nairn, a little wistfully, "The whole thing made traceability easy, prioritization easy, phasing of implementation easy—and costing a nightmare! Once the requirements were agreed, phases agreed, project costed and price agreed, everyone knew what was going to be done."

That doesn’t mean that every software requirements document should be 200 pages long. The appropriate level of detail varies by job description, by application domain, and certainly by corporate culture. Even then, you should expect contradictions.

Your quality assurance department usually wants a lot of detail. Jim Hazen, a professional QA tester in Colorado, wants requirements defined well enough for him to write test cases. That means, he explains, "They have a level of information beyond the typical, ’We want an application to do X, Y and Z.’ They should have information that states more of what the requirement is to do (the What) and the way it is to do it (the How)."

The software requirements are supposed to enable developers to improve application consistency (especially in large projects) and to reduce the guessing game of, "What does the user want?" Damon worked on one project that used Use Cases as its requirements repository. 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 dialog 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!" remarked Damon.

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 anymore, no matter how poor it is."

1 2 Page 1
Page 1 of 2
Download CIO's Roadmap Report: Data and analytics at scale