How to Write Good Requirements for Test System Integrators

1.      Did you read it?

That’s right, I asked that. This is the “is it plugged in?” question of requirements writing. Many times, we get requirements that are just handed down from a prime contractor to us that don’t make sense in the context of what we need to deliver. We don’t need to know about the requirements you need to fulfill, we need to know about your requirements for us. Sometimes that means taking an already large requirements document and rewriting it from the viewpoint of you to us. That may be a lot of work, but do it. It will save everyone a lot of headaches.

Make sure that if you are copying and pasting from another doc that you actually read what you have pasted to make sure it coheres with the rest of the document.

2.      Do your requirements expect the reader to be a mind reader?

Often, we get requirements that are actually a description of the widget that the customer already has and needs tested, controlled, or monitored. That can often be useful information about the system we have to connect to, but we really need to know what you want us to make for you. Keep your requirements for us focused on what you want from us.

Likewise, when writing requirements for an integrator you should assume we don’t have the insight and internal knowledge that comes from years of working directly with your products.

3.      Is each requirement describable in a clear and concise manner?

If the requirement can’t be stated in 1-2 sentences, then it is probably too complex and needs to be broken up into easier to understand chunks. If more elaboration is needed, then that can be added to the overview or background at the beginning of your requirements document or you can find a way to add a notes section for each requirement without muddling the requirement statement.

4. Is the result measurable?

If this is a requirement that can be tested with a functional test, then it needs to have clear passing criteria. “Measured voltage > 10 V.” “Throughput = 10 Mbps.”

5.      Can you verify it?

No? Then it’s very likely that we can’t either. This is where common sense needs to play a part. If you can’t think of a way to validate the requirement then it might be unrealistic. Sometimes, it is just a lack of test equipment. Other times, it means that the opposing system to test the built system just doesn’t exist. In that case you may need to realize that you will be paying the subcontractor to build some kind of test system as well as the delivered system.

6.      Can you explain the verification process in simple terms?

I don’t think the entire test procedure should exist here, but if you can’t summarize how this will be verified, then it needs to be rethought. This will be a good guide for whoever is writing the actual test procedure. They don’t have to guess as to how the original writer envisioned the requirement being verified. t is a good idea to think about how you are going to verify each requirement as you’re writing them.

7.      Did you write an essay as an intro?

This isn’t a college entrance exam. A simple purpose statement and some background on why you need this work done is great and usually very useful for context. After that, though, focus on short, concise requirements. A table or some repeating section structure is best.

Once the summary of the system and needs are done, there is no more need for long winded paragraphs. State the requirement name, the description (“it shall do this”), verification method (at least inspection and functional test), verification procedure (high level overview), and expected ver ification results (what constitutes a passing measurement).

8.      Do requirements contradict each other?

This is especially important to check for if you are copying requirements from other documents.

9.      Are the users of the system defined?

It helps to know who will be using this system and how. What is important to their success? If you define this well at the beginning, then you can refer to these users (even with a fabricated name) throughout the document.

10.      Do you use the word “shall” to describe what the system needs to do?

“Shall” should be used for most requirement descriptions. Other words (will, must, can, should, could, has to) can be confusing as to what is mandatory and what is optional. Keep it consistent throughout the document.

11.      Is the word “will” used to describe interactions with the system by the DUT/user/external system/etc.?

“Will” should be used when talking about users of the system or equipment that connects to the system to describe how they interact with it. Try not to use “will” for requirement descriptions. Stick to “shall” for those.

12.      Do any requirements use conjunctions?

Then you probably have more than one requirement in that description. Break it up into two or more requirements that each make a single statement about what is needed.

13.      Is it free of vague absolutes?

This is one of my personal favorites. “The system shall be free of errors.” Every system throws errors. No software or hardware is absolutely perfect and when things go wrong we sure do want to capture those errors. Usually, it is best to collect them in a file or database, but we want to capture them none-the-less.

“The system shall never fail.” Really? Are you running this until the end of time? Who will run this forever testing? Make sure you know what you’re asking for. In high reliability scenarios, think about what is realistic and appropriate. “The system shall have no more than 1 min of downtime every 30 days” is much more reasonable. That’s a tough requirement, but it is measureable, testable, and can ultimately be verified. Just understand what that means. You must come up with a way to test that requirement and likely for a period much longer than the actual passing parameters. Also, realize that it may need to be repeated if it fails and fixes have to be applied.

14.      Is the requirement explaining a need or a want?

Keep the requirements to your true list of needs. Wants can be added in as optional items that you can have quoted as additional cost, or just save them for a second phase after you have some hands on time with the system and learn more about what you really need.

15.      Is the requirement telling your integrator how to do their job?

You’ve hired an integrator to do their job and you should let them do it. There are some cases where dictating some of the design may make sense so that it fits within an existing ecosystem, but likely you are hiring someone because you don’t know how to build the system you need. You are the subject matter expert on your product/industry/etc.; you are hiring an integrator because they are the experts at implementing systems, so let them design the way that is the best and fits within their tool chain and knowledge base. Keep the design specifications out unless it is absolutely necessary.

So, are there some things you can do to make your requirements smell nicer? Likely. Are they terrible? Probably not. As we all know, there is always room for improvement and this is an area where I see customers often missing the mark. This requires more time up front for us to do detective work and figure out what the real requirements are. And if we are still left with doubts, then we should build in extra time to try to compensate for that risk. As doubts and risks go down, accuracy of your quote goes up, smiles get bigger and business gets repeated.

We can often help you improve your requirement writing ninja skills, but the better the starting point, the better the end result is for everyone. Want us to give you some feedback on your requirements? Reach out here.