If brevity is the soul of wit...

Than clarity is the heart of development. Projects begin with a requirement, often vague and frequently unrealistic(1). From these dreams low level requirements are created (2). In turn, they are developed into derived requirements(3).

So what makes a "clear" requirement? There are multiple papers such as this, or this or even this. At the core, all of these recommendations can be expressed as 6 basic concepts

1. Requirements shall be measurable and testable.
2. Requirements shall use consistent terminology.
3. Requirements shall be expressed in the affirmative (4)
4. Requirements shall be short, containing only the information required to define them. (5)
5. Requirements shall be written in clear an unambiguous(6) language.
6. Requirements shall be traceable through out the development cycle.(7)

Given these fundamental guidelines how does this relate to Model-Based Design (MBD)? The answer is both everything and nothing. MBD is a software development process and like all processes it functions best when there are clear requirements driving the work (hence the "nothing"). However, unlike traditional code based (e.g. C, HDL) development processes MBD provides multiple methods for interacting with the requirements to improve traceability and testability of the requirements (hence the "everything")

The takeaway

Writing and maintaining requirements is sometimes seen as burden on the development process taking time away from the "real" work.

This perception arises, I think, from three factors. First poorly written and second out of date requirements both of which makes their usability suspect. The third is overly specified requirements (e.g. writing code in the requirements) which leads to duplicated work. Following the "clear writing" guidelines addresses the first two issues(8). The final "line in the sand" issue of when to stop writing requirements and start creating algorithms I will end with this quote

"When you find yourself writing how instead of what you have moved beyond your requirements"(9)

Notes

1.) Unrealistic requirements are not in-and-of themselves a bad thing. They become an issue when, in the refinement stage, they are not turned into their realistic brethren.

2.) "Low level" can also be viewed as "foundational" requirements, e.g. the things you build on.

3.) Yes my image is a reference to the quote that "One does not simply walk into Mordor." Given hobbits love of ponies I thought this was best.

4.) Affirmative language: e.g. "the wizard will stop monsters from passing" rather than "though shall not pass"

5.) Requirement "creep" is not uncommon. It is when the implementation "creeps" into the requirements.

6.) It may actually be hard to determine what "unambiguous language" is;

7.) I include trace-ability in the clarity requirements because it enforces

8.) It is much easier to keep well written requirements up - to - date then poorly written ones.

9.) I wish I could attribute the quote, it stuck with me from an early systems class I took back while working at the Ford Scientific Research Labs.

BIO

Michael Burke is a consultant with The MathWorks and former coordinator for the MathWorks Automotive Advisory Board (MAAB). I currently focus on Model-Based Design Process Adoption and Establishment projects. Views expressed in this article do not represent the views of The MathWorks.