How to Compile High-Quality Requirement documents

How to write good requirements

Writing Requirement documents is very common in the field of embedded development. The requirement document is used to define development tasks and coordinate large-scale R & D plans. For the final product, the requirement document plays the role of communication between developer behaviors and consumer behaviors. When the requirement document is correctly written, it can play a huge role. However, if you have been working in the embedded development field for a long enough time, you will soon find that there are too many unqualified requirements documents in this field. When you try to fix these unqualified documents, you will soon find that it is not easy to write the correct Requirement documents. Here, we provide some suggestions to make it clearer to write the correct requirement document.

At a higher level, the purpose of writing a requirement document is to provide a valid description of the required behavior. The required behavior can be described by a black box system. Pay attention to the following details:

• Engineers can implement it according to the system.
• Testers can use the device verification requirements that meet hardware requirements without communicating with developers.
• The final results meet the requirements of end users.

• Black box testing

　　Write high-quality Requirement documents:

　　The most basic principle is that the requirement document should be as concise as possible, and the system's expected behavior should be constrained with the most understandable description.If you follow this principle, the rest of the important factors (testability, avoiding excessive design, etc.) will become logical.

Listing more detailed rules is usually helpful. The following are the steps to write high-quality Requirement documents:

1. Define the boundaries of the system. This is also necessary for the black box system.

2. Define input and output. This should also be the only way you can view the internal system.

3. Describe the expected behavior of the system in the most understandable way

4. Apart from input and output, does your requirement involve other parts of the system? If yes, your requirements will be over-designed. Refactor the demand to make it simpler.

5. Are your requirements too ambiguous? Add more limits. Note: ambiguous descriptions are not a bad thing. If all the situations contained in the description are acceptable and no additional information is required for testing, then it doesn't matter. You do not have to (or should not) limit the system's behavior.

6. Can your requirements be tested? (This refers to the black box test) if not, you 'd better return to step 1. If this type of rework occurs many times, it means that your black box cannot correctly describe the system, or your testing tool is not good enough. In either case, non-testable Requirement documents are almost worthless.

7. Is your requirement document easy to understand? If your requirement documents are hard to understand, it means that you are not well-written and can only bring endless pain to those responsible for implementation according to your needs. If so, go back to step 1.

8. Have you really achieved step 2? Are you sure you want? Check again.

　　Example:In the following example, let's describe the need for a self-made embedded device that can read the bending frequency from the Bending Sensor and make an LED flash based on different frequency values.

Obviously, we have completed steps 2 and 3!

· Input: read data from the Bending Sensor.

· Output: LED.

However, we skipped step 1:

· In this example, we will draw the black box to the microprocessor of the device.

Let's continue,

　　Step 4:Besides input and output, do we have other system boundaries?

· The microprocessor does not care about what data is read from the Bending Sensor. From the processor's perspective, it only needs to measure the voltage of the ADC foot.

· The LED is only controlled by the digital output foot.

Next, let's fix this problem:

0th requirements:

1. The device should switch the status of the digital output end based on the voltage at different frequencies of the ADC foot.

　　Step 5:Are requirements ambiguous?

Well, our description is too ambiguous. How fast does the output switch take? What is the relationship with voltage? What is the input voltage range? Let's add more detailed descriptions:

Release 0.1

1. The output end should be controlled by a free-moving Timer

2. The frequency of the free-running timer shall not exceed 10 times per second or less than 1 time per second.

3. The trigger frequency of the Self-running timer should change linearly between the highest and lowest values, and be proportional to the input voltage at the ADC end.

4. The input voltage at the ADC end should be read every 100 milliseconds

5. When the input voltage end of the ADC is read, the registration value that controls the cycle time of the free-running timer should also be updated.

6. The effective voltage range of the ADC input end should be controlled between 0 and 1 v.

　　Step 6:Is your requirement testable?

· First, the free-running timer does not need to be mentioned here, because it basically cannot be tested in the black box. It is neither input nor output, and there is no connection with the two.

Let's use "the frequency of changes at the digital output end should be controlled between 10 times per second and 1 time per second" to replace the test standard for the free-running timer.

· For the fourth requirement above, some minor modifications may be required to serve as the test standard. Let's describe it with "input voltage at the ADC end should be read at least once every 100 milliseconds", which makes our expected test behavior more understandable.

· The fifth requirement also requires some minor modifications. How can we detect that the voltage output range is between 0 and 1 V? I can't always give a 2 V voltage. Can I see if the components have been burned out?

Then, it would be much easier to say, "check if the system works normally when the input voltage at the ADC end is between 1 and 2 volts. The requirement description should be "positive" and should describe the behavior of the device "should", rather than the behavior of the device "should not. Otherwise, the test will fail.

Release 0.2

1. The switching frequency of the digital output end should be controlled between 10 times per second and 1 time per second.

2. The switching frequency at the digital output end must change linearly between the maximum and minimum values, and is proportional to the input voltage at the ADC end.

3. The input voltage at the ADC end should be read at least once every 100 milliseconds

4. Check whether the system works properly when the input voltage range of the ADC is between 0 and 1 v.

　　Step 7:Are your requirements easy to understand?

Compared with our original description: "controlling led flashes at different frequencies based on the output of the Bending Sensor", the requirements described above are hard to read and understand.

I found that the most simple way to make the requirement documents easy to understand is to extract details and define them separately in the form of entries.

Version 1

1. the Bending Sensor should ensure that data is read at least once within 100 milliseconds (put in a comment separately)

2. Switch the led status to make it consistent with the reading of the Bending Sensor.

3. when the reading of the Bending Sensor is 1 volt, the number of switching led status should be kept at an average of 10 times per second; when the reading of the sensor is 0 volt, the number of LED switches should be kept at one second.

Definition:

· Bending Sensor: the input voltage is at the X end of the ADC. Safe voltage ranges from 0 to 1 volt (listed separately in the comment)

· Led status: The number status is output by Y.

This is much better (although not perfect ). These requirements are easy to understand, do not involve internal implementation of the system, and are easy to test. Limits on system behavior are limited to what needs to be done. (For example, the sampling frequency of the Bending Sensor can also be higher, as long as no unexpected behavior is generated, everything can be done ).

Writing requirements is like building software in the brain. Therefore, it is more important than practice.