When Bad Software Requirements Happen To Good People

  March 08, 2011

Software requirements can’t be too vague, but they can’t be so detailed that nobody can read them, either. The people charged with gathering and documenting software requirements may have the best of intentions. But more often than not, the final product is either lacking in detail or way over the top—and not what the end user wanted.

For Michael Feldman, coming up with software requirements is akin to what he quaintly refers to as “analysis paralysis.” Feldman, vice president of engineering at Big Belly Solar, a global provider of waste management solutions in Newton, Mass., says many developers who write code “get so wrapped up in the process of creating the requirements, you end up with a War and Peace book that is out of date as soon as you finish writing it — and no one can follow it except the original writer.”

Ask developers what the sole cause is of software requirements being too in-depth or too bare bones and you’ll hear one phrase echoed time and again: failure to communicate. The main issue in projects that go astray, they say, is a lack of understanding just what the requirements are because inevitably, they aren’t clearly articulated early on.

Kill the Messenger

“[The business analysts] aren’t specific enough and the programmers don’t get what the analysts are saying,’’ says Alex Papadimoulis, managing partner of Inedo, a custom software development company based in Berea, Ohio. Papadimoulis is also editor of The Daily WTF, an online how not-to-do guide to software development.

Ambiguity is a big problem, Papadimoulis says, because the person who wrote the software thinks it means one thing, but the person who reads it thinks it means something completely different. “It’s like building a house. If the blueprints aren’t specific enough and don’t specify the color of the walls, and that was a big item to the customer … that would be a case of completely misguided requirements,” he says. Software development requires a good analyst in the requirements-gathering process, Papadimoulis stresses, since customers often acknowledge that they don’t know what they want. “They’ll say what they think they want, but it’s an analyst’s job to determine what the customer needs based on the problem they have.”

When it comes to requirements gathering, the written word is worth its weight in gold, according to Hank Wallace, owner of Atlantic Quality Design, a consulting firm in Fincastle, Va., who has a background of more than 30 years in software, hardware, and system design. “Every program should be specified by a written document, which is studied and evaluated by both management and the programming staff,’’ Wallace noted in an article he wrote entitled, The Unspoken Secrets of Software Development. “I have seen a verbally-specified project run 400% over schedule because of communication problems and misunderstandings. There is no question as to whether a written specification is desirable.”

John Uhri, a freelance software developer based outside of Chicago, has sat on both sides of the aisle. Once, when Uhri was a consultant on a project, someone on the sales side who supposedly had a technical background was charged with the requirements gathering. After that was completed, the person put together a quote for the client and then gave the requirements to the technical team. “After the first meeting with the client we said, ‘Hey, there’s a lot more to this’ and we ran it up the flag pole and started screaming from the rooftops. We knew our company was going to take a bath on the project if we continued,” Uhri says.

The requirements the developers were given were to take a spreadsheet and create a web-based application so people could fill in answers, which Uhri says would have been very simple to do. “But when we started talking to the client it went from being very static to very dynamic and data driven because they wanted to be able to make changes to the web front end,” he says. The tech person who had done the requirements gathering and who was the project’s liaison told them to just forge ahead anyway. “It turned out that the scope was four to five times what the requirements actually were,’’ Uhri says. “We had been led to believe the project would take about a month and it ended up being four months.” Uhri says he wasn’t involved in pricing the project, but estimates it ended up costing his company three times what the original quote was.

That incident taught Uhri never to do a fixed-bid project. It also led him to the conclusion that developers should be the ones to come up with an estimate because they’re the ones who have to implement the software. In addition, he says, “Make sure you’re very careful what you agree to with a client; you need to be able to control scope.” Uhri says this was one of the first projects his former consulting firm did offsite. It wasn’t long after that they went back to doing onsite placement of developers.

Overdoing It

Another time, when Uhri was a business systems analyst at a mobile auto glass repair company, he was responsible for gathering requirements for a project that involved redesigning a mainframe application to run on a client/server platform. Uhri met with end users from various departments to get their requirements and document them. The project was outsourced to an external company that was building the application. The project was fraught with problems and undergoing a second round of iterations by the time Uhri was brought in.

“The first time, there wasn’t enough documentation. The second time I documented the daylights out of it and there was too much documentation.” Consequently, the developers couldn’t see all the details through the volume of requirements he had generated. “I went through and designed screen shots and what every error message was supposed to say and what everything should do and their eyes kind of glazed over,’” Uhri recalls wryly. “They missed things because there were two giant volumes of documentation.”

Eventually the application was deployed; Uhri doesn’t remember how long it took but says it definitely added more time to the pieces that needed to be reworked. “It should have taken a good year’s worth of development and I’m sure it got pushed back a quarter or two.”

Big Belly Solar’s Feldman also remembers a project he was responsible for building when he worked in the telecom industry that contained way too many details. It was a management application to control telecom equipment on a Unix-based workstation.

“We went through myriads of requirements documents and functional and design specifications, and we ended up with so much documentation we used up our development time,” Feldman says. “You spend so much time including in the plan the time it takes to write the documentation, you waste a lot of valuable time getting the features in.” This also becomes an issue for developers if the documentation is outdated by the time it is finished, he notes.

That leads to the antsy factor. Developers tend to get impatient to start writing software when they have a deadline, but before they have the green light. “There are a lot of undercover activities that go on in software engineering because in general, guys don’t want to spend time writing documentation,” says Feldman, adding that he found this to be very typical in the telecom industry. “They like writing code and that’s what they’re paid the big bucks to do.”

The various stakeholders in the management application project had a difficult time agreeing on how to word the requirements and the way the developers were proposing to do something. “It became a fine game of balancing ‘Let’s go and write something,’ with ‘When they tell us what they really want we’ll go back and adjust it.’”

Today, as a manager, Feldman says he almost feels compelled when he hires a developer to put a piece of paper in front of them saying this is how a system works, and this is how something needs to be written. Echoing Papadimoulis and Wallace, Feldman says point blank, “I want a good communicator; a good verbal and written communicator.”

Feldman believes there is no magic bullet to finding the right balance to getting software requirements right. Too much documentation stifles productivity, and too little can get you burned. Ideally, nothing beats getting in front of a customer throughout the different development phases, Feldman says. “I prefer to show them a prototype of an actual product to get feedback. It’s much more powerful and you get to have a meaningful conversation.” But that depends on the type of industry you’re in and the size of the company you’re at. Since it’s unrealistic for every developer to get to meet face to face with every customer, Feldman suggests lobbying to ensure that your project liaison is “somebody in the organization who is the voice of the customer in a productive way; who knows the goals of the project and is tied in to the needs and feeds of the customer.” Of course it’s out of the developer’s control how savvy that person is, but you can still assess their ability to be the true voice for the customer.

“My word of advice is, ask questions and be doubtful,’’ he says. “It’s OK to continually ask detailed, pointed questions to really ferret out the political agenda versus the real business case.”

Feldman also believes strongly that projects stay on track when developers bite off software requirements into as small pieces as possible. “So build five in the next month and see how that goes and get feedback. I believe that’s also a way to mitigate problems that may develop.” Feldman also suggests a method he has shifted toward using: a PowerPoint-approach to gathering and documenting requirements.

“When you write in a language like Java, for example … you have the ability to include documentation within the software itself so it lives there and you can produce self-documenting code.” His chosen tool, Javadoc, explains what the software is doing, so he doesn’t have to spend a lot of time writing traditional design documentation, Feldman says. “As software programs are helping society be more efficient, there are tools within the software engineering community that have helped as well. It makes our jobs easier while we still search for that balance.”

See also: