Software Requirements Versus Product Specifications: Divining the Differences

Can’t get no satisfaction? Try to read between the lines. What users say they want may not be what they need.

contract“You’ve got to be very careful if you don’t know where you are going, because you might not get there,” said Lawrence Peter Berra, a.k.a. Yogi Berra, the baseball hall-of-famer and former Yankee catcher. Even better, the master-quipper said, “If you don’t know where you are going, you might end up someplace else.” That’s pretty smart for a guy who called eighth grade his senior year.

Yogi was perfectly describing a vexing conundrum faced by software developers when talking to users about their problems.

Inside the blue box

It’s surprising how difficult it is for clients and users to simply tell you what they need and to describe the problems that you are qualified to address. Here’s the essential problem. When users describe to developers what they need the software to do, often the users give specifications rather than functionality needs.

It’s not a matter of “who is at fault,” as tempting as it is to adopt that attitude. If the user was a developer, he’d think like a developer. He isn’t; that’s why he brought in the expert (you and your development team). For example: Developer asks User, “What problem are you trying to solve?” User responds, “We want a blue box.” Developer, “Well, you’re expecting a blue box will solve the problem, but it may not. What’s the problem you need us to solve?”

Sometimes the “blue box” answer isn’t quite so clearly given. It can be easy for developers to respond to the stated “need” – after all, we all want happy users – without realizing that we haven’t addressed the actual business requirement. Bad things happen if you take that wrong turn, so I urge you to pay attention during this “vision” stage.

Early in my career, I was a graphic designer designing movie titles, 1984 LA Olympic graphics, corporate identity projects, and product point of sale campaigns. I encountered the same issues as development teams do today, and I found a few ways to address them. One solution that worked: I finessed my questions so that clients helped me create a “Design Criteria Document.” It got clients to illuminate on how they wanted their corporate image to impact their customers’ perception of them, among other factors. The answers could be, “A high end, elite line of cruise ships, marketing customized global cruises.” I steered away from accepting answers like, “We like Bodoni style type and want to see lots of navy with nifty little wave patterns.” (But that doesn’t mean I didn’t hear that sort of thing often.)

The old-style waterfall development process of developing software leaves much to be desired. Developers work against a pre-defined specification document, which says, “This is exactly how the software will work, where every T is crossed and I is dotted.” It’s especially frustrating to develop software this way if the software specifications are written based on delivering that blue box, which doesn’t solve the problem. Of course, by the time the software (blue box) is released for real-time duty, the users in question realize it’s not really what they wanted.

Another way to look at this conundrum simplistically – and to perhaps guide your users when they try to give you Blue Box answers – is to compare the software development process to moving into a new house. You might sketch out where the furniture goes in the living room. When you get onsite, you put the couch where the sketch says it should go, but it doesn’t fit, or it looks lousy. Doh! So you start moving around furniture, rugs, etc. to come up with a solution that works. If you get stuck on designing the living room layout in too much detail, it becomes impossible to make changes that are necessary.

The world doesn’t work according to super-specific specification documents; but we can define problems and create solutions that address them.

Taking a page from… oh my… the Marketing department

Let’s begin with the admission that there is no single process that development teams can implement to guarantee a 100% success rate. What teams can do is conduct due diligence to gain a clear understanding of their customers’ and user departments’ corporate culture. Then they can work closely with the stakeholders to understand and document established workflows which the software needs to address or integrate with.

This is a process with which a company’s marketing department may be familiar – even if they aren’t quite as comfortable with the process when they are on the customer side of the table. A Market Requirement Doc (MRD) usually precedes a Product Marketing Document (PRD) and Technical Specification Document. The MRD lays out the problems that the software needs to solve and what the enterprise user needs the software to do. That’s all determined before the designers start working on creating the answer.

If the developers are working in conjunction with Marketing, it may help to speak their language. For example, “We need a website to serve consumer e-commerce customers,” or “Our existing business partner portal needs a way to access the site from a mobile device.” The MRD might be drafted by the tech staff (in a “Here’s what I heard you telling me” manner), or it might be created collaboratively with those users.

The user department (both its managers and representatives of the end users) should sit in on meetings with developers (and sometimes IT) early in the process. This is where the users explain what they need. Get the user to tell a story, explain what they are trying to achieve. Agile people call these “user stories” or “use cases.” Be unrelenting about asking questions to draw the user back into the workflow explanation and the problem definition when they head down a specification path, away from their story and needs description. The documentation will be much more powerful and useful downstream.

Only after those goals are clarified should you think about the option of a Product Requirements Documents (PRD) to succinctly describe the software’s purpose, features, and functionality. It is not a road map, but does specifically lay out where IT expects the application to go. This is the document that developers actually use from which to build and test the software so it has to be comprehensive. Technical specification documents typically evolve from the PRD.

Steve LaBrie, Vice President of IT, for the Patina Restaurant Group, describes the process he used to build the company’s data warehouse. His discovery process included numerous meetings with stakeholders, GMs, and VPs of units. Much of what they used was taken from existing Excel sheets and automating those business workflows. LaBrie noted, “Beyond that, they didn’t really know what was possible, so we built it and showed them what reports the new system was capable of on the fly.”

LaBrie shared, “After we built the data warehouse, we had all this data at our fingertips. Managers would ask how they could pull up numbers (like how many steaks were sold versus chicken, and what the kitchen labor costs were for each item).” His solution was to have the stakeholders (or in this case, steakholders) mock up what they wanted in an Excel spreadsheet, or draw a sketch on a piece of paper and send it to him. LaBrie couldn’t have his team build the report on an ethereal description. “Once we knew the problem that the manager wanted us to solve, we backfilled from the data warehouse.”

Every project’s discovery process is unique to the company, and to its business, industry, and culture. The key to delivering a successful project lies in accurately focusing conversations with users, clearly understanding the purposes of each document, and knowing what each should communicate to meet the business demands. If you get it right, you’ll end up with accolades from your company’s executive team on down, and avoid having to sheepishly adopt another Yogi Berra quip, “We made too many wrong mistakes.”

End user involvement is key to winning them over with your enterprise applications. Agile development methodologies allow you to keep all stakeholders involved and work iteratively, course correcting as the project is completed. The Mendix App Platform comes with an easy-to-configure feedback mechanism that allows end users to provide development teams with issues, questions, and ideas on the applications they’re using. These feedback tickets are sent directly into an agile project management module, where they can be planned into sprints and even mapped back to the page they were on when they clicked “submit feedback.” Sign up to see Mendix in action.

The App Platform for the Enterprise - Build New Enterprise & Mobile Apps
in a Fraction of the Time - Get started for free!

Questions? Chat With Us