The Requirements are in the Requirements: A Guide to Systems Engineering Requirements Management

A fundamental step of the systems engineering process is requirements development and breakdown. Writing good requirements is a skill… and in most situations, an art form. The NASA Systems Engineering Handbook has a great checklist covering How to Write a Good Requirement, so we won’t cover that in this blog post (but we may be back with more info on that in the future!).

What we will cover is how engineers should use these requirements when designing their systems - and specifically how to use the data values within these requirements.

The data values are in the requirement

A common frustration in systems engineering is the disconnect between requirements and the technical data values stored within these requirements.

Requirements are written in a way that makes sense from a human perspective; they have a clear statement, technical data values, are grammatically correct, are verifiable, etc. A well-written engineering requirement is very human-readable: a human can read the requirement, generally understand what it means, and extrapolate from the requirement how it can be verified.

As an example, let’s consider the following systems engineering requirement:

The system shall weigh less than 20 kg.

Excellent. I have a system. And it shall weigh less than 20 kg. And it's even expressed as an SI unit!

Since the requirement is a "shall" statement, I know that at some point, I should have a means of verifying this requirement.

Maybe we’ll weigh the system and verify it’s less than 20 kg (assuming we’re on Earth and not getting too pedantic about mass vs weight…). Or, as we design the system, we could ensure the total weight of the individual components of the system don't exceed the maximum weight described in the requirement. There are plenty of options!

But what's important is that I, as a human, can read and generally understand the information conveyed by this requirement. And I can make a plan to verify that this requirement has been met at some point in the design process.

The data values are in the requirement?

Now let’s assume I’m a computer-savvy engineer tasked with keeping track of the total mass of the system. A systems engineer, project manager, or maybe just my boss said, “hey this is your requirement to meet, keep track of it!”.

Let's also assume I'm a savvy engineer who's taken a few hard knocks in the school of real world engineering. I know that although the requirements are "fixed" right now, it is highly likely that they will change. I also know the communication of this change may not always flow down to me in a timely manner.

I'd like to avoid the following situation in a few weeks:

It's 8:00 AM and I'm having my first cup of coffee. I receive a panicked phone call (the day before a big design review) informing me that the total mass of the system can now only be 18 kg. The system I've designed currently weighs 19 kg. My original requirement was to be less than 20 kg.

I now have to shave off 1 kg of weight ASAP before the big Critical Design Review with the customer!

Panic ensues for the next days as we frantically find a solution.

I'd like to avoid this fiasco and plan ahead for any changing requirements. More importantly, I know my boss and project manager are busy. They may not always communicate these changes to engineers in a timely manner.

We'll extrapolate from what I do know. Most well-organized project managers will be documenting requirements somewhere. It will most likely be in a web tool like Jira or Confluence or a spreadsheet application like Microsoft Excel or Google Sheets, but the data values should be kept up to date in this tool.

Let's also assume that I like to tinker. I realize I can set up a script to regularly poll this documentation for the latest engineering requirements. I can spend a few days and integrate these values into whatever home-brewed widget I've developed.

With all that work done, I get the value out of that system and into the tool I’m using to calculate the mass of my system. Only to realize that the value I pulled in is in the format of… a human-readable STRING.

The system shall weigh less than 20 kg.

The tyranny of the regex

The data value here I need is the INTEGER (probably better to cast it to a FLOAT and assume it has decimal precision) stored in the string.

Now, to get to this point, I already had to jump through a few thought experiment hoops that may, dear reader, lead you to think, “why not just check the spreadsheet and copy-paste the value from it every week or so?”  Let's assume I enjoy automating everything, especially boring tasks, allowing me to be more productive with the high-value portion of my engineering job!

Back to the problem at hand. The data values are in the engineering requirement. But, the requirement is just a string, that I as a human can read and understand, but it’s not very machine-readable.

There are many powerful Natural Language Processing (NLP) and Machine Vision or Machine Learning (ML) technologies out there. I could throw a regular expression at this string to pull out the numeric values. But this is fragile. It will probably work 80% of the time, but it will require a lot of nursing, nudging, and tinkering to get to 100% recognition of data values in every situation of a human-readable requirement.

Eventually, no matter how impressive my regular expression is, I can expect the following response from my machine:

Well, dear reader, if you’ve made it this far I’m happy to tell you that we’ve been building a systems engineering software product called Verve that solves this problem and enables your teams to take systems engineering into the 21st century (without the help of Hal 9000!)

Machine Readable and Human Readable

At Prewitt Ridge, we created Verve for systems engineers, built by systems engineers. We know that for a systems engineering tool to provide the features engineers expect in the 21st century, requirements must be both human-readable and machine-readable.

Engineering requirements must be human-readable for engineers, designers, and project managers to look at the requirement and say "Yes, the system needs to weigh less than 20 kg." But, part of the secret sauce of enabling systems engineering in the 21st century is also ensuring the data values of the requirement are machine readable.

We believe that machine readability is one of the core features for innovation in systems engineering. Having a machine readable requirement allows for a distributed, authoritative source of truth. Instead of copying and pasting a value from their requirements management tool, engineers directly reference the requirement or data values in their engineering tool (whether it's Excel, Python, Matlab, SolidWorks etc.). This ensures the data value is continuously up-to-date and in sync with remote storage of this requirement. More importantly, it also allows project managers to understand where requirements and data values are being used in the engineering process. As your team integrates machine readable requirements into their engineering process, innovations like continuous integration and automated risk analysis and management are also possible.

To get started, here's how you can write a machine-readable and human readable requirement in Verve.

1. First, Create what we call an “Atomic” value for the System weight:

2. Next, when writing the human-readable requirement, reference the Atomic instead of a plain text value:

That’s it. The human-readable text is human-readable, but the technical data values are stored in a machine-readable format – a format that is referenced within the human-readable requirement.

Anytime your atomic value changes, the human-readable requirement is automatically updated to the latest and greatest value of the machine-readable technical data value.

Bringing Systems Engineering into the 21st Century

Our approach to this storage of requirements is simple. We parametrized the technical data values so they can be maintained separately from the requirement, but still accurately represented in the human-readable requirement.

This may seem like a small change. But at Prewitt Ridge, we believe parametrization of requirements is the foundation on which innovative approaches to engineering design are going to be built upon in the 21st century.

The atomic storage of data values allows them to be referenced directly in other tools. This architecture forms the basis of building distributed, authoritative sources of truth; building powerful integrations into your engineering design tools of choice; building continuous integration pipelines into the hardware engineering process; automating the generation of compliance documentation… and much much more.

If you’d like to learn more about how Verve can be part of your 21st engineering tool suite, reach out to us to learn more!