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.