Writing Better Requirements & Specification – Tip Sheet

1. Explain the system from the perspective of what needs to be accomplished by the integrator.

Often requirements and specs don’t make it clear which aspects of the system are actually just a description of the parts of the system that the customer already has or plans to take care of themselves, and which aspects need to be developed by an integrator.  The former can often be useful information, but it’s important to differentiate between what the system needs to do overall, and what new work needs to be completed.  Keep requirements focused on new work to be accomplished.

2. Make requirements 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.”

3. After you draft the requirements, step away from it for three days, and then re-read it.

It’s easy to be in a rush and just want to hurry to get the requirements out the door because then you can get started on the project, right? Wrong. You’ll end up spending just as much time (or more) iterating with the integrator to get to something that everyone understands, often at the expense of increased frustration.

4. Remember that the integrator is not a mind reader.

The integrator may or may not have some past experience similar to your application, but chances are they don’t have the level of insight and internal knowledge that comes from years of working directly with your products.

5. Make 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.

6. Can you verify it?

If you can’t, then it’s very likely that we can’t either. This is where common sense needs to play a part. If you can’t determine a method to validate the requirement, then it might be unrealistic. Sometimes, it is just a lack of the right test equipment. Other times, it means that the equipment to test the built test 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.

7. Did you write an essay as an intro?

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.

State the following info:

• Requirement name
• Description (“it shall do this”)
• Verification method (at least inspection and functional test)
• Verification plan (high level overview)
• Expected verification results (what constitutes a passing measurement).

8. Do any of the 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.

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.  Are they free of vague absolutes?

Here’s a requirement you don’t want to see: “The system shall be free of errors.” Every system throws errors. No software or hardware is absolutely perfect and when things go wrong we want to capture those error (usually in a file or database).
“The system shall never fail.” 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.

13. 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.

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’re hiring 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 as they see fit based on their tool chain and knowledge base. Be mindful of when your specifying design vs requirements.

If you’d like us to give you some feedback on your test system requirements, you can reach out to us here. If you’d like other useful info, check out our test system resources.