How to write a quality requirements document

Writing requirements documents is a common situation in the field of embedded development. Requirements documents are used to define development tasks and thus coordinate large-scale research and development programs. For the final product, the requirements document plays a role in the communication between developer behavior and consumer behavior. When the requirements document is written correctly, it can play a huge role. However, if you work long enough in the embedded development field, you will soon find that there are too many unqualified requirements in this field. And when you try to fix these unqualified documents, you quickly find that writing the right requirements document is never easy. And here, we're going to give you some advice on how to make it clearer about writing the right requirements document.

At a high level, the purpose of writing a requirements document is to provide a valid description of the desired behavior. The required behavior can be described in a black box system, with the following details to be noted:

• Engineers can be implemented according to the system.

• Testers can take advantage of device validation requirements that meet hardware requirements without communicating with developers.

• The resulting results meet end-user requirements.

Black box test write quality requirements Documentation:

The basic principle is that the requirements document should be as concise as possible, with the most understandable description to constrain the system's expected behavior. If you follow this principle, the remaining important factors (testability, avoidance of excessive design, etc.) will become logical.

It is often more helpful to enumerate more detailed rules. Here are the steps you need to follow to write a quality requirements document:

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

2. Define input and output. This should be the only way you look at the internal system.

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

4. In addition to the input and output, your requirements are also related to the other parts of the system? If so, then your needs are too designed. Refactoring the requirements to make it leaner.

5. Is your demand too ambiguous? Add more qualifying specifications. Note: Some ambiguous description is not a bad thing, assuming that all the circumstances contained in the description can be accepted, and that the test does not need additional information to explain, then it does not matter. You don't have to (and should not) limit the behavior of the system too much.

6. Are your requirements testable? (This refers to black box testing) if not, you'd better go back to step 4th. If this rework happens many times, it means that your black box does not describe the system correctly, or that your test tools are not good enough. In either case, an testable requirement document is almost worthless.

7. Are your requirements documents easy to understand? If your requirements document is very difficult to read, it means you are poorly written and can only bring untold pain to those who are responsible for the implementation of your needs. If so, go back to step 3rd.

8. Did you really do the 4th step? Are you sure?

Example: In the following example, let's describe a requirement for a homemade embedded device that reads the bending frequency from a curved sensor and blinks an LED according to the different frequency values.

Obviously, we have completed step 2 and step 3!

• Input: Read data from the Flex sensor.

• Output: LED.

But we skipped step 1:

In this example, we will draw the black box onto the device's microprocessor.

Let's move on,

Step Fourth: Do we involve other system boundaries besides input and output?

• Microprocessors do not care what data is read from the Flex sensor, and from the processor's point of view, the only thing to do is to measure the voltage of the ADC's foot.

The LED is controlled only by the digital output foot.

Now, let's fix this problem:

Requirements for version No. 0:

1. The device shall switch the state of the digital output terminal according to the voltage of different frequencies of the ADC foot.

Fifth step: Need to write ambiguous?

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

Version 0.1

1. The output end should be controlled by a free active timer

2. The maximum frequency of free running timer must not be higher than 10 times per second, not less than 1 times per second.

3. The trigger frequency of the free run timer should be linearly varying between the highest and lowest values and proportional to the input voltage of the ADC end.

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

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

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

Sixth step: Are your needs testable?

• First of all, free running timers are not required here to mention. Because it is basically impossible to test black box, it is neither input nor output, and it has nothing to do with the two.

Let's use the "digital output change frequency should be controlled at 10 times per second and 1 times per second" to replace the free run timer test standards.

• For the above fourth requirement, some minor modifications may be required to be used as a test standard. Let's say that "ADC-side input voltages should be guaranteed to be read at least once every 100 milliseconds" to describe the test behavior that we expect to be more comprehensible.

• Demand fifth also requires some minor modifications. How can we detect the voltage output range between 0 and 1 volts? Can't always give a 2 volt voltage, and then see if the components have been burned?

So, to say "the test system in the ADC end input voltage between 1 to 2 volts, the work is normal", so the test is much easier. The requirement description should be "positive" and should describe the behavior of the device "should" rather than the device "should not". Otherwise, the test will fail.

Version 0.2

1. The switching frequency of the digital output port should be controlled between 10 times per second to 1 times per second

2. The switching frequency of the digital output should be linearly varying between the maximum and the minimum value and proportional to the input voltage of the ADC end.

3. ADC-side input voltages should be guaranteed to be read at least once every 100 milliseconds

4. Verify that the system works properly when the input voltage range between 0 and 1 volts is in the ADC terminal

Seventh step: Is your demand easy to understand?

Compared to our original description: "Control the flashing of LEDs according to the output frequency of the bending sensor", the requirements described above are difficult to read and understand.

I've found that the easiest way to make a requirement document easy to understand is to extract the overly detailed stuff and define it separately as an entry.

Version 1

1. The bending sensor shall ensure that the data is read at least once in 100 milliseconds (put in the note separately)

2. Switch the status of the LED so that it is consistent with the reading of the bending sensor

3. When the bending sensor reading is 1 volts, the LED state switch should be kept on an average of 10 times a second, and when the sensor reads 0 volts, the number of LEDs switched should be kept at 1 times a second.

Custom：

• Bending sensor: The input voltage is at the x end of the ADC. Safe voltage range is 0 to 1 volts (put in note separately)

LED Status: number state output by Y-end

This is much better (though not perfect). These requirements are easy to understand, do not involve the internal implementation of the system, and easy to test. Limitations on system behavior are limited to what needs to be done. (for example, the sampling frequency of a curved sensor can be higher on the implementation, as long as it does not produce unexpected behavior, everything can be).

Writing requirements is a process of building software in your brain. Therefore, it is important to perform the operation.

How to write-requirements