Dissecting the requirements document

To begin any embedded system-level design, the developer needs a clear understanding of what the final software design must accomplish. The source of this information is the system requirements document, or simply the requirements document. The requirements document should contain the functions required, their timing, their communications needs, and their priorities.

At this level, the general organization of the software needs to be developed, including definition of the tasks, layout of the communications, determination of the overall system timing, and the high-level definition of the priority structure.

These four areas—tasks, communications, timing, and priorities—are the four basic requirements for multitasking. The development of the system tasks includes context switching, but for our purposes, it is expanded to include 1) the creation of the tasks; 2) the development of a communications plan to handle all the communications between tasks; 3) a timing control system to insure that each task is active at the right time to accomplish its function; and, finally, 4) a priority manager to shift execution time to those tasks that are important to the system at any given moment.

If the requirements document does not contain all of these answers, and it typically doesn’t, then it is up to the designer to obtain this information. The answer may come through asking questions of the department that generated the document, such as Marketing. Some of the information may be implied through a reference to another document, such as an industry standard on RS-232 serial communications. And, in some cases, the designer may simply have to choose.

Wherever the answers come from, they should end up in the requirements document. As part of the design, this document will be a living entity throughout the design process.

As the requirements change, either through external requests from other departments or through compromises that surface in the design, the changes must be documented and must include an explanation of the reason for the change. In this way, the requirements document not only defines what the system should be, but also shows how it evolved during the development.

Some may ask, “Why go to all this trouble? Isn’t commenting in the listing sufficient?” Well, yes, the commenting is sufficient to explain how the software works, but it does not explain why the software was designed in a certain way.

It can’t explain that the allocation of the tasks had to be a certain way to meet the system’s priorities. It can’t explain that halfway through the design additional functions were added to meet a new market need. And it can’t explain why other design options were passed over because of conflicts in the design. Commenting the listing conveys the how and what, while the requirements document conveys the why.

An effective shorthand technique is to also list the information in a design notes file. This file should be kept simple; a text file is typically best. In this file, all of the notes, decisions, questions, and answers should be noted.

Personally, I keep a text file open in the background to hold my design notes when I dissect a requirements document. That way, I can note important information as I come across it.

Another good reason to keep a design notes text file is that it is an excellent source of documentation for commenting. Whether generating a header comment for a software function or source information for a user’s guide, all a designer has to do is copy and paste applicable information out of the design notes file. This saves time and eliminates errors in typing and memory. It also tends to produce more verbose header comments.

The process discussed in your article to make requirements more and more precise is interesting. But I have the feeling it is sometimes mixing up Requirements, Specification, and Design. Isn't Specification a precise description of WHAT a user wants (requirements); and Design a description of HOW to implement the Specification (the WHAT) ? So what you are describing looks like what happens in an an iterative development process.

Congratulations Kevin! This is a very good and educational article. I learned one or two things here. Of my special interest was in regards the user interface design. Defining the relation between the frequency of use of a function and the number of clicks or menu deepness level is a very good point. One call of attention though (and I hope you consider it as constructive criticism) is that on page 4, table 3.1 the frequency of use is reverse to what you recommended on the previous paragraph. You stated to put the most frequently used on top and the least on bottom. Though I’m now thinking perhaps you did this on purpose to get some comments? Not needed though, your article is good for what it says… looking forward for part 2.