Writing requirements: Common sense measures for success

Experts offer simple, common sense measures for writing requirements that deliver software that's better for the business.

Software pros have heard this story a hundred times: Faced with writing requirements for an application development project, business stakeholders don't really know what they want, and problems proliferate all the way down the line. Development can't code requirements accurately. Quality assurance can't develop meaningful tests. And when the new app makes it into production, business stakeholders say it doesn't do what it needs to do.

"The way software requirements are done is still broken," said Jama Software CEOEric Winquist. "Requirements are a continual conversation from the beginning of a project through development, testing and delivery." Too often, teams cut that conversation short just as the writing requirements process is getting underway, he said.

Team members don't work hard enough to understand the stakeholder's definition of project success.

That's one reason why requirements -- and hence software projects -- fail. Experts interviewed for this article offered several others. They said team members don't work hard enough to understand the stakeholder's definition of project success, and they fail to get testers on board early enough. In addition, project managers and business analysts make it difficult for stakeholders to take part in the approval process. And they reinvent the wheel with every new application, when in fact, some software requirements can be reused.

In this article, experts offer commonsense measures to help teams do a better job of writing requirements. Taken alone, each step is relatively simple, but collectively they produce better requirements, which in turn results in better software.

Guide stakeholders to be more specific

When requirements expert Nancy Nee works with clients, one piece of advice she offers is this: When business stakeholders explain what they want an application to do, keep asking questions. "It's common for them to say, 'Honestly, all we need is access to these reports so we can generate our own status report.'" That's the beginning of the requirements conversation, not the end, said Nee, vice president of global product strategy at consulting firm ESI International, in Arlington Va. The next step is to dig deeper, asking questions such as: How quickly do you need the information from the report; do you need to generate the report every month; what day of the month? With this information in hand, summarize the stakeholder's need, Nee said. "In order to understand the impact of an invoice on the budget, you want to be able to enter this query on an invoice, and run this report on the 28th of each month."

Winquist, CEO of Jama Software, in Portland Ore., agreed that software teams often wrap up requirements too soon. "People have early discussions about the problems that need solving," he said, but then the software team drops the ball. Ongoing conversations enable teams to come up with better, more specific requirements. "Each step of the way things are broken down into more and more formal descriptions," he said.

Get software testers involved early

Too often test professionals are the step-children of software projects, Nee said. "They don't get enough information to define tests properly." To avoid this, get testers involved in requirements at the project outset. "If testers are simply [the recipients] of requirements, the project will run into trouble," Nee said. She recommended project managers and/or business analysts work closely with test pros to develop use cases, and then translate the requirements into tests cases that are easy to execute. "The testers need to get a view of how the application works at every point," Nee said.

Define success from the stakeholder's standpoint

A common mistake that software professionals make during the requirements process is they do not explicitly ask business stakeholders for their definition of success. This simple step results in better requirements, Nee said, elaborating on her earlier example. "Say something like this: 'So, if you have the report no later than 10 a.m., on the 20th day of each month, would you say we have been successful with the requirement?'" If the answer is "yes," document the stakeholder's agreement. If not, go back to the drawing board, she said.

Foster software requirements reuse

Documenting requirements is not just a matter of proving stakeholders have signed off. Winquist pointed out there is a much bigger benefit of keeping track of requirements conversations: the opportunity to reuse that requirement in other applications. "The goal is to operationalize requirements to save time and ensure consistency down the road." He offered two examples where reuse of requirements is often possible: security requirements and marketing requirements. He elaborated on the second example. "The company branding message may apply to 2000 different apps," he said. "You need to look at your portfolio and say, 'Show me every place the corporate logo is used and let's make sure the updates have been made.'" This is not difficult to implement, but software teams don't make the effort, Winquist said. Requirements evolve over the course of many conversations, electronic and in-person. "You have the knowledge in-house, and it's important to capture it."

Requirements follow the business rules

Another step that's easy for software teams to overlook is the way business rules or policies affect application requirements, Nee said, offering an example. "Let's say you're working on a software project that lets employees submit expenses for approval and reimbursement. You have to factor in the company rules around payment," she said. If the application is designed to issue a check as soon the expense report is approved, it will violate a company policy that, for example, specifies checks are cut on the 15th and 30th of the month. "When the supervisor approves an expense report, the business rules get called," Nee said.

Ease the sign-off process for project stakeholders

Long, mostly text documents, that spell out software requirements are standard operating procedure for traditional application development projects, said David Nyland, CEO of Blueprint Software Systems Inc., in Toronto, Ontario, Canada. But when asking stakeholders to approve the requirements they worked on, these documents are a bad idea. "No one reads them -- but people will sign off and say they did," Nyland said. And of course, that will cause trouble down the line. A better approach is to present stakeholders with only the information that is directly relevant to them -- and to present that information visually. "You want to show the process flows, the use cases, the UI mockups," Nyland said. "No one wants to wade through that big 600-page doc."

What are your tips for getting software requirements right? Email SearchSoftwareQuality.com editors and let us know.

Dig Deeper on Topics Archive