How to Write Good Requirements, Pt. I of III

Finding the requirements management sweet spot means being concise, specific and parametric, and answering the question, “What do we need?” rather than, “How do we fulfill a need?”

In the post below—the first of three transcribed from his Writing Good Requirements workshop, with notes and slides from his presentation deck included—Jama Consultant Adrian Rolufs explains common problems teams go through, and how to avoid them.

= = Start Part I = =

Today I’m going to be speaking about product definition and how to ensure that you are using requirements correctly and to maximum benefit.

A bit about myself: For the first 10 years of my career I worked in the analog and mixed-signal semiconductor industry, first as an applications engineer and later as a product definer.

As a product definer I became a customer of Jama Software. Adopting Jama to manage requirements completely revolutionized how I built products. So much so, that a couple of years ago I joined Jama Software to help as many teams as possible benefit from using Jama.

Product development teams face many challenges, but the ones we are going to focus on today are how to systematically navigate the path from a high-level market need to the specification of an actual product.

Specifically, we’ll be looking at this challenge in the context of development teams that work from a specification, but the concepts apply to all development.

So, the ultimate question is, really, why do we write requirements at all?

Requirements are a tool that guides the journey from the vast number of possibilities for products we could build, to determining whether the product we want to build is going to be successful or not, down to picking exactly the right product we’re going to build.

Particularly in systems and hardware development, designers are typically not able to start developing a product until there are sufficiently detailed requirements, or possibly even a specification.

So for the purposes of the discussion today, I’m going to use the term product specification to mean the detailed document that describes what the actual product is, the final result of the development process.

One way of looking at this challenge is shown below. Imagine that the orange circle is every product that a given team knows how to build, and the blue dot is the exact specification for a particular product. The specification defines exactly which product the team will produce.

Let’s say we have a product we’ve developed, and we have the specifications that go along with it that tell us exactly how it works, how well it performs, size and cost, and requirements are the guide we use to get through those.

In many industries, you have to have a fair amount of detail fleshed out before teams and resources get assigned and dedicated, so there are milestones to meet as you go through this. So, you’ll get some level of detail and you have a milestone to review it. You’ll get more detail; you’ll have more milestones.

Usually in the process, companies follow step by step guides for getting into the details, but there is usually a lot of room for interpretation along the way, so we’ll talk about some of the structures you can apply along those ways.

In more iterative environments, perhaps more software-type environments, you might actually go through this loop much, much more quickly, so you might do all of this but still focus on a very specific function and do it in a couple of weeks.

The same concepts are still applicable; it all depends on the scope of the product, time frames, interactions, and things like that. What we’re going to talk about here, in terms of systematically defining what to build, applies to almost any kind of product.

So, one of the first steps is defining the overall kind of space that the product team is going to operate in, and that’s typically done with a market definition or market requirement document, or something along those lines.

There are different approaches to doing that. The approach I recommend is defining that solution space with problem statements and constraints, because problem statements are clear descriptions that answer the question, “What is this product supposed to do such that it adds value to the market?”

So, if the product solves a problem that a lot of customers have it should sell well, and if it does it meeting the constraints, this should also result in it selling well. This is kind of the starting point for our product development process.

This might include, in addition to the problems that it’s solving, certain amounts of functionality that are required for the industry. The right amount of performance, functional and non-functional types of requirements, schedules, and things like that. This is really a kind of visual way of thinking of a market requirement set.

Important things here are not over constraining the development team or the design team. If these requirements are so specific that we can only build one product, then there is not a lot of room for the teams to innovate. If the requirements are really vague, the teams don’t know what to build, so we’ll talk through that next.

So the first example—and this is a common scenario that a lot of teams face— is that the solution space or the market requirements are so vague that the design team doesn’t know where to start.

It could be they’re too high-level, say, a problem statement with no constraints, in which case the design team doesn’t know whether the solutions that they can think of are valid solutions to those problems or not.

From the perspective of a designer, the detail that a marketer can provide is usually insufficient. So many questions remain unanswered, that either they go and build something, and it doesn’t end up resulting in a successful product, or they ask a million questions, that the marketer doesn’t have answer to.

The problem is that while the blue space is completely enclosed here, it typically isn’t. Many more detailed requirements are needed to fully enclose the box. Specifying those details completely will also likely dramatically shrink the blue area.

Even though, this approach is clearly problematic, many teams fall victim to it. Designers may feel that they can’t trust marketing because they know they aren’t getting enough detail and often have experienced failed products as a result of it. Marketing doesn’t understand why designers can’t just get on with building the product and why the products are missing the target, late, or both.

It could be there are other factors not considered, and so a lot of times this results in design teams starting to ask lots and lots of questions, which is good. It’s better they ask those questions than don’t, but it does mean that you possibly spend a lot of time iterating in this phase of the project because there’s not enough definition around, well, what problem are we trying to solve and what are some valid constraints around that?

The other possibility is the design team might say, “Hey, we can build whatever we want,” and they proceed without asking questions. It might be brilliant or it might be a complete failure, but because there are no controls for predictability, it’s definitely a high-risk situation.

Another common scenario is that the market requirements are so specific that the design team doesn’t have room to innovate. The market requirements could be a copy of a competitor’s specification with a couple of lines changed to say, “Build me one of these.” Or it could be a previous specification produced by the company with a few modifications that say, “Improve everything by five percent.”

Those kinds of requirements documents tend not to lead to a lot of innovation. It’s okay to have them, because sometimes you need to make a derivative part that’s just a quick improvement to an existing device; this can be very successful in the market.

But if you have too many of those types of products it becomes more difficult as time goes on to react quickly to new requests because you don’t have new technology. By focusing on modifying your existing technology, you’re likely falling behind in the competitive landscape with your customers.

You want to have a good mix of products that are defined in such a way that innovative technology can be developed. Design teams can go solve creative problems using their engineering skills, and that’s really the biggest benefit to the overall organization; it also makes the engineers happier because engineers love solving problems. If you just say, “Build me one of these,” they’re usually far less satisfied and far less enthusiastic about working on a project.

All right; so the third common scenario where this can go wrong is you define what your problem statement is, you have constraints, you think you’ve got a really well defined solution space, and the team goes off and builds something. And along the way the team finds there are challenges in the design, make some changes, and build a product that simply doesn’t meet the original requirements.

Marketing may have provided high-level problems to solve with constraints initially, but the focus moved to agreeing on a specification. As design challenges come up and trade-offs are made, the specification slowly drifts outside of the blue “acceptable products” area.

The result is that the team is so focused on building that they end up not building the right thing.

While this can be addressed by periodically reviewing the specification against the high-level requirements, there are likely many details in the specification that do not clearly trace to any high-level requirements.

As a result, the team doesn’t actually know they are building the wrong product.

When teams say, “Okay, we can make that change,” but don’t have a “live” source of traceability back to the requirements, problems are guaranteed.

This is very common scenario when managing the process in documents and spreadsheets because it’s very difficult to actually have traceability in those kinds of tools.

And what happens as teams go through the discussions and make the compromises, is that they stray from solving the original problem, meeting the original constraints and focusing on the original solution space.

Now, sometimes you get lucky and you can still sell what you’ve built, but what I’ve found in the industry overall is that as time has gone on, things have gotten sufficiently more complicated such that the chances of one these products being successful is decreasing.

It used to be that if I got things wrong, using what I built for another application was possible. That’s rarely case with today’s complex systems.

= = End Part I= =

Author
Recent Posts

Marc Oppy

Marc Oppy writes about requirements management, requirements traceability, developing safety-critical system and software requirements, systems engineering, and tips on how to write better requirements.