specifications Archives

Tag Archive for: specifications

Using stakeholder, system, hardware and software requirements to build a professional wireless microphone.

In the post below—the last 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. (See Part II here.)

==Start Part III==

Let’s look at an example product using my audio background. I’m going to take a circuit that goes into a professional wireless microphone—the kind of high-performance microphone you’d see someone on a stage, like a MC or a musician, use.

It’s got to be able to handle a wide, dynamic range, meaning it has to be able to record very loud signals and very quiet signals, all with very high quality, and it’s got to be powered off of a battery so that it can he handheld, meaning the connection to the system will be wireless.

So we’re going to talk about some of the requirements that go into the chip; one of the main chips that goes into a solution like this.

First we’ll start at the market or stakeholder requirements level. Often, they’re called stakeholder requirements because stakeholders can be more than just customers.

In most product development organizations customers have requirements, but internal teams also have requirements.

So if I’m building a chip, for example, I have quality requirements that my quality department is going to dictate, but will also be influenced by the customer’s requirements.

And I probably have a production test organization that has to test every one of these devices as they go out the assembly line.

These devices are going to have requirements concerning what kind of access they need to internal circuits, and what kinds of circuits they need to enable them to test in a timely manner—things like that.

The development team might also have requirements; for example, they need to be able to reuse certain amounts of existing circuitry to stay on schedule, or requirements around data costs.

The point is that what we call stakeholder requirements is really a broad category. It could be anybody who has an influence on the product development.

Let’s look at some examples—these would most likely come from customers—which would be focused on the functionality and performance of the device. I’ve got three examples here: One is good and recommended; two are not.

We’ll start with the first one. Say we need a product that can input a microphone signal, convert a signal with two digital audio signals, have two different gain stages and consume less than 20mA while operating.

This is the sort of thing you’d likely hear directly from the customer but not necessarily the sort of thing I’d want to write down as requirements.

This brings up a couple of issues.

First, I’ve got a bunch of requirements mixed together, so it would be easy to miss something, and also it presupposes a certain solution.

It could be this is the right solution, but it assumes certain solutions, so it’s talking about internal details that are over‑constraining the design team.

The team can come up with a different gain structure that works and achieves the results, but doesn’t use 20dB and 0dB of gain. What’s wrong with that? Why do I need to over‑constrain them?

So those are some of the problems with the first one.

Second, customer X needs a 140dB microphone amplifier with a digital output for less than 50 cents. The microphone amplifier shall be low power.

This is the sort of thing marketing might write, because it’s focused on the customer’s request: They need it at a certain cost and everything should always be low power.

It’s very difficult to actually meet these kinds of requirements.

140dB—well, what is that? That’s just a ratio number; I don’t know what that actually is a measurement of. I need some more specificity around that.

As for 50 cents, you have no idea what the solution is yet so 50 cents may or may not be achievable, but it’s good to know.

And then the last one, low power; that can mean almost anything. Low power in one industry could be high power in another, so specificity around what low power means would be beneficial.

So in that case, the first example is more specific and has more detail—although both of the first two are not very atomic so it would be easy to miss things.

The last example talks about two things.

The first one has a problem statement. I love problem statements because they really tie back to the value the solution can offer. It’s giving me some context around what’s in the market today and what the problem is.

It’s saying in the market there are high dynamic range microphones which transmit digitally, and it requires circuitry that’s expensive and large or high power to obtain the necessary performance.

And from that I know that a solution is out there, but that solution is difficult, hard to use or hard to implement, and it can be expensive and it may or may not provide the necessary performance.

You can see how this helps outline the idea of what kinds of problems I need to solve and where the most value is in design.

So based on this, I would know that hitting the audio performance is important, and getting a small solution size that’s low power is also important; those are the key constraints.

To make that have a specific power consumption, say the solution shall consume less than 75mW while in operation.

Now, the other benefit here is 75mW; it’s an actual power number, whereas in the first example I had a current but without knowing the voltage I don’t what the power consumption is, so that’s also not a great example.

So in this case, the last one is the one I would recommend; it has more constraints and a good set of stakeholder requirements. With that, the design team has a good idea of what their goals are, but they’re not over‑constrained.

Now for the next level of detail: Once we have a set of stakeholder requirements, or at least a draft, we can start looking at system requirements. The system requirements are what we’re actually going to build a product against.

We’re not going to build a product directly against the stakeholder requirements because we could have multiple stakeholders and we need to consolidate their requirements into one set.

Or, certain stakeholders may ask for things that we actually end up not satisfying, but we still know that we can build a successful product.

So that translation from stakeholder requirements to system requirements provides the clarity and explicit decisions around what we’re going to do, what we’re not going to do, and what the actual requirements are for this project.

Now, one of my favorite examples of system requirements is the first one—absolutely nothing—and I see this time and time again.

I can’t count the number of times where I see people skipping the system requirements when they’re building a system.

If you’re an engineer responsible for low-level details, how do you know if those low-level details are the right details? Well, you need system requirements first, so we definitely don’t want to skip this level.

Now, the next one: The solution shall have two differential inputs using instrumentation amplifiers. The instrumentation amplifiers shall be followed by sigma‑delta ADCs. These are really low-level component requirements.

We’ve already jumped to the conclusion that we’re going to have a specific architecture in the hardware. What if part of the solution needs to be software? We haven’t said anything about that and we could already be over‑constraining the design team when some other architecture would be more appropriate.

It could be an instrumentation amplifier is not the best choice. We don’t need to constrain that at this level. So the last example here is really a better example of system requirements.

What about power consumption? It’s going to 20mA while in operation. I said before, current on its own is not necessarily the best example. With this you would typically provide a supply voltage range so then it would become clear.

What about the signal levels? Stating what the signal range needs to be provides a lot of detail around what the architecture of the design needs to be, without over‑constraining it.

And then, the overall end‑to‑end, signal‑to‑noise ratio: 140dB A‑weighted gives me a very clear statement of the overall performance, again without over‑constraining.

So for system requirements I like that last one.

These system requirements are all focused on the performance of the signal path. There should also be some system requirements here that talk about constraints on size, constraints on packaging and things like that.

Now we know we need to build something that consumes relatively low power, takes in a very wide dynamic range signal and maintains the quality of that. So we can start talking about architectures in response to these system requirements.

Let’s say we use a hardware device that has analog to digital conversion with two signal paths, both of which have medium performance but which we can combine together to obtain high performance, and that’s actually the common solution in the application.

And then we use a software algorithm to combine those signals, so we’re going to need a DSP to run the software algorithm and process the signal to output this resulting signal of 140dB A‑weighted signal noise ratio.

Based on that, we can now talk about the hardware‑specific requirements.

Here are some examples of different possibilities. The first one is a block diagram of the architecture.

I’m visual; I love block diagrams. I love schematics because they’re very intuitive. I can relate to them very well. They don’t make good requirements, unfortunately. It’s very difficult to test a diagram. It’s very difficult to make sure you didn’t miss anything in a diagram. So having a diagram on its own is not sufficient.

A really good solution is a diagram complemented by a set of requirements that attach to every important detail of that diagram.

That way, visual people have something to see, but we also have atomic requirements that we can test against and trace to make sure we didn’t miss anything, and also so we can manage changes.

If I make changes to this diagram based on changes to the architecture or customer requirements, it might be hard to actually know what those changes were, whereas if I have individual requirements I can track, I can easily know.

The second example is just a description of functionality, a response to the requirements. This is saying what the signal path of the device is; the architecture is describing a specific part number. This is down in the design descriptions where this belongs. It’s not hardware requirements.

So the last example is one I like for hardware requirements. We’re talking power consumption; we’re getting more specific.

We know that I’m building a chip, the power consumption is going to vary and I want to know what it’s typically at and what its maximum can be, so we’re specifying that.

Again, we’re repeating the input signal level because that input signal level was a requirement on the system that’s also a requirement on the hardware.

There is some duplication, but it’s there to explicitly say that this is a requirement on the hardware. I won’t see a requirement for 17uV RMS to 1V RMS on the software, because the software is never going to know about volts; it’s going to know about digital signals.

So even though there is duplication it’s done to make the decisions and the traceability explicit. So then I have requirements on the specific architecture.

Now that we’re down at the low-level and component requirements, the hardware requirements, we can start talking about specific solutions. We’ve got to get into the details of what the solution is actually going to be.

So in this case, in the hardware requirements, you’ll likely see requirements that dictate a certain solution, but that’s okay because it’s quite likely that the design team is the one writing these requirements, so they’re the right ones to make that decision.

As you probably have guessed by now, the last one is my recommendation for well‑written hardware requirements.

The last example is software requirements.

I see a lot of teams that just skip software requirements entirely and go straight to writing code. It’s really fun to write code, really satisfying, but if you don’t have any requirements, you’re starting without clear directions. We need some requirements.

The second example, some descriptions of functionality, is written as a shall statement. It sounds like a requirement but I’ve got a bunch of stuff mixed together.

I’m talking about two signals. I’m talking about what their performance is. I’m talking about the output. There is too much stuff mixed together here, so the third one is the recommendation: talking about specifics.

I am going to develop this software for a specific DSP, the Tenscilica HiFi 3. It’s going to perform a specific function. It’s going to take two audio signals and it’s going to combine those into one.

(Note: I’d probably need more detail around this. This is probably not enough by itself but I didn’t want to fill the screen with the requirements.)

And then, what’s the sample rate going to be? This algorithm is going to be designed for a specific sample rate or multiple sample rates. It’s an important characteristic of the algorithm. Let’s make sure that’s captured in requirements.

So that is exactly what I would recommend, and in each of these there are a lot more requirements that go along with this. These are just a couple of examples in each category.

Many teams mix up requirements and specifications. It’s very common.

You need to make sure you have a clear understanding of each of them and when to use them. It’s not always easy to decide which one is which, so it’s absolutely critical to have that discussion with your team.

What I see a lot of teams doing is skipping levels of hierarchy, jumping straight from high-level customer requirements down to detailed requirements or detailed specifications. Do that and you’ll have a very difficult time proving that you built the right thing.

It could be you’re operating fast and loose and you’re okay with that. Maybe that’s okay for a very small team in a very small organization. But in every other situation, it’s unlikely that you’d be building something so uncomplicated that you could get away with it. It’s high-risk.

So make sure that you have at least stakeholder requirements, client requirements and some kind of detailed specifications.

That’s the bare, bare minimum for any kind of product. More likely you need more.

What I recommend: Make sure you have a clearly defined process with clear levels of your requirements. If you don’t think you have that, discuss it with your team. What levels do you need? Which one of those diagrams [more in posts Part I and Part II] would be appropriate for your project?

And then there’s the scary question: Do you even use requirements?

Some teams plow ahead without requirements. Think about what kind of problems that can cause:

Maybe you’ve built products that have not been successful, that maybe needed a late change or maybe even failed, and you had to develop a new product in order to be successful.
Perhaps you’ve been in a situation where you later learned you missed some important details along the way and realized that you barely got away with it. That’s high-risk too.

When you start with an understanding of the roles different levels of requirements perform, you’re less likely to invite risk and add complications during development, and are much more likely to build the right product.

==End Part III==

Key differences between requirements and specifications, why different levels of requirements are important, and how to establish a clear requirements hierarchy you can use and change to suit any product, version or variant you build.

In the post below—the second 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. (See Part I here.)

==Start Part II==

These days, products are so complicated they can only be used in specific scenarios and for specific applications, which means that if you don’t build a product right, chances are there’s no home for it.

Potentially millions of dollars of development efforts, not to mention sales, are lost if you’re unable to thoroughly keep track of the requirements all the way through.

So we’re going to talk today about some ways to avoid those problems and really set yourself up for success.

What’s most important is having a systematic process to follow; you want a logical progression that takes you from the high-level to the low-level details in a structured way, because that leads to the best results.

It’s actually more important than how you write the requirements.

So the first key point I want to make concerns differentiating between requirements and specifications, and here the word “specifications” is a nebulous term. It’s used differently in different industries.

In many, “specifications” means a document that contains something, a requirement specification, a verification specification or a list of verification test cases.

By the way, I’m using the term “specification” here as the semiconductor industry does. The specification is a list of the performance, the functionality and the features of the solution; it’s the end result. It documents what you actually produce.

In many cases, there is a document called a datasheet that’s the customer facing version of this. So if you’re familiar with datasheets, think of the specification as the datasheet.

For the purposes of this discussion, here are the differences between requirements and specifications:

Requirements

Requirements reveal what the product needs to do
The tool we use to identify the right product to build and to ensure we’re building it right
The tool we use to communicate internally about what the product needs to do and how it needs to work

Specifications

Specifications detail what the product actually does
Specifications are not useful to identify the right product to build
The tool we use to communicate externally about what the product is and how it works

Typically, requirements are a little higher-level and a less explicit than specifications.

But when you combine the two, what you get is a clear statement of a need and a clear statement of what you’re going to do to satisfy that need.

In doing so, you document exactly what you’re doing and why, and this helps capture the decisions that are made along the way and why they’re made.

However, what I typically see is a document that has intermixed requirements and specifications.

It’s an easy and logical way to write, but it’s very difficult to refer back to afterward for facts and analysis.

So what you end up finding out is, although what you did made sense at the time, you missed some things along the way. There were some high-level requirements that you’d forgotten about.

For example, I was recently working on a product that had only 30 requirements, but discovered that when I wrote the documentation and the specification, I missed one, even though I had written the requirements and solution myself on the same day.

It’s very easy to miss things without a systematic approach in place.

I found what I’d missed only because I’d built the traceability from my specification back to the requirements. I had to prove that I’d met every single requirement and that every one of my specifications was there because of a requirement.

By doing that, it reminded me of something that I missed, so it really saved me some trouble.

This oversight may have come up at some point during reviews, but maybe not, because it’s impossible for anybody to remember every single detail.

Having the requirements separate from the specifications and traceability links between them is critical for making sure you don’t miss anything or end up with features that you don’t need, which add cost or schedules to the product.

Separating the two is difficult if you’re not used to writing that way. Often, I will write, or other people will write, in a traditional kind of document style, and then extract from that what the requirements and the specifications of the solution are.

In other words, you can take an iterative approach to this, and that’s totally valid.

Now, the next question is, how do we get to the right solution? The answer is, by having a clear hierarchy.

So what I’m showing here is a basic hierarchy with market requirements and product requirements. It’s probably the simplest level of requirements you can possibly have in any product development.

The market requirements capture what the customer needs and what the market as a whole needs, and the product requirements say what the requirements are, for the product that we’ve agreed to build.

We can trace back to those customer requirements in such a way that we can prove that the product we’re building is going to satisfy the market requirements, and that we don’t build anything extra.

This is the basic minimum.

You can think of each as a documentation task, but they also follow the phases of your project. When you’re capturing marketing requirements you’re also thinking about what possible solutions you could be developing to satisfy those market requirements.

You’ll likely come up with product concepts, or maybe just one product concept, depending on the situation. And so you would capture, in addition to the requirements, some architectures or concepts that go along with that; that’s the “black box” for all the market requirements.

Same for the product requirements. Once you have them—or while you’re writing them—you’re thinking about the architecture of your solution and the trade-offs you might need to make.

This informs what requirements you can satisfy and which ones you can’t.

By writing the requirements in conjunction with coming up with a design, when you’re done, you have a clear statement of requirements and a solution that can meet them.

Before I came to Jama I was an engineer, coming up with new products, and I sometimes focused only on the product concept and the product design, and skipped a lot of the requirements.

It’s easy to fall into that trap. Engineers love solving problems. We don’t love writing down the requirements for solving those problems. But without those requirements we don’t know whether our solution is the right solution.

Some teams might have, say, only market requirements and no product requirements, or vice versa.

But what they don’t have is a clear distinction between what the customer asked for, or what the market needs and what the team is doing to address both.

As a result, it’s difficult to know whether they’re building the right thing or not.

Now, if your product is complicated you add hierarchy to this model.

Let’s say, for example, I’m doing chip development and my chip has a whole bunch of different internal blocks that are all each fairly complicated in of themselves.

Well, then I can add another level of hierarchy, which I’ll call block-level requirements.

A block requirement would be probably something specific to a chip, or a system where you have a hardware device and it’s made up of sub-circuits.

For example, say I have a digital chip that’s a microcontroller. One block might be a digital interface. Another might be the memory. Another block might be the analog interface.

Or, say I’m building a bigger system, and Engine Control Unit, or ECU, for a car. The ECU is my system. And that ECU is made up of a microcontroller and interfaces; they are components of the system.

Whatever you’re building, you want to break it up into logical pieces; those are your components—which you’ll be wanting to write component requirements for.

So product requirements would describe what is needed from this whole chip overall, and that chip, for the purposes of the requirements, is really best thought of as a “black box.”

But then the block-level requirements say, now that we have a product architecture in mind, what the requirements are for the individual pieces. The designers are going to go and design against those block-level requirements.

For example, product architecture says we’re going to have an ADC, an Analog Digital Converter.

We would then need block-level requirements to say what the performance for this ADC is: What does the power consumption need to be? What does the size need to be it needs to fit into a certain space? What kind of input signals and outputs signals does it need to have?

Things like that.

And then the block design would tell me how this ADC is architecture. What’s the topology? What circuit components are coming together to satisfy those requirements?

Again, having both of those pieces of information is critical.

In this example, what sometimes happens is the product requirements section gets skipped. People already know the architecture, to a certain degree, and so they jump right to the block-level requirements.

The problem with that is market requirements are very high-level and block level requirements are very detailed, so skipping requirements means teams can’t forget a single thing during building.

But the most serious problem is having no traceability back to product requirements; without it, teams can’t confirm the connection between block-level requirements and market requirements.

Without traceability, it’s difficult to know for certain if this block-level requirement traces to that particular market requirement.

You end up missing things, so each of those levels is important.

Now, it could be you are building something even more complicated, so you need to add levels of hierarchy.

Basically, the more complex your build, the more hierarchical structure you want in place.

Here’s a system example; in this case we have both hardware and software, so we have system requirements that describe the overall needs of the system, and then we have an architecture that says, what’s going to happen in hardware, and what’s going to happen in software.

And based on that architecture, we can then write requirements for the hardware and for the software.

We can architect the hardware and the software, and then we can again write low-level requirements for the individual pieces of hardware and the individual pieces of software, and then write the design details that go along with each of those blocks.

So again, you take a systematic approach going from high-level customer needs all the way down to design, and you just adjust this based on the levels of complexity of your product.

And as your products get more complicated, it’s entirely possible that you start off with something simple and you add complexity to the next generation, and maybe you add even more complexity in the next generation, so you have to adjust the model based on your product complexity.

But it’s very unlikely you’ll use the same model forever.

When I was an engineer, we were really more focused on market requirements, product requirements and the block requirements model. Recently I’ve seen a lot more of the system requirements, especially in the chip industry.

Many of the products coming out of chip companies these days are more like systems than ever, so this model ends up being a good place to start.

You can cut out pieces out that you don’t need, but make sure you have accounted for all the pieces that you do need. Having that discussion with your team is really critical to setting up the right model.

==End Part II==