Some Alternative Requirements Views

NOTE: This is article # 3 of a four articles series, where I describe why it is so valuable to create various views of your requirements. I’ll tell you about some of the analysis models and other techniques you can use to represent requirements information and give you some ideas about how to choose an appropriate model. You can find the first article here: The Six Blind Men and the Requirements

An effective business analyst doesn’t just “write requirements.” Instead, the BA should think about the most appropriate way to represent requirements-related information in a given situation. Besides the traditional default of writing natural language statements, the BA should determine when a picture or some other representation would be valuable. This article, adapted from my book, More about Software Requirements (Microsoft Press, 2006), briefly describes some alternative types of requirements views to consider.

Analysis Models

Analysis models are diagrams that present information visually. The table below lists several of the graphical analysis models that are available to the BA. Some of these date back to the structured analysis movement of the 1970s and 1980s. Others are part of the Unified Modeling Language, which provides a rich set of conventions for object-oriented analysis and design. I don't have the space to describe these various techniques in detail here. See my book Software Requirements, 2nd Edition (Microsoft Press, 2003) for descriptions and examples of several of these modeling notations.

Note that some requirements authors use the term model to describe any method for representing requirements information, including a list of textual functional requirements. When I say model or analysis model, I’m referring to a diagram that represents requirements information visually, generally at a higher level of abstraction than written requirements offer. I highly recommend that you use standard notations when drawing these kinds of diagrams. There are enough types of models in the software literature to cover nearly every situation, so you should almost never have to invent a new kind of diagram. Remember that these are communication tools. If you make up your own kind of picture using some other language of symbols, no one else will know how to read it. This rather defeats the purpose of communication. Instead, take the time to learn about the various modeling notations. You can practice with them by documenting an existing system, so you learn which types of models are useful for showing certain kinds of information.

Some Graphical Analysis Models for Representing Requirements

Decision Tables and Decision Trees

These are tabular and graphical techniques, respectively, for representing complex logical expressions (such as a sequence of if/then statements) and the associated system behaviors. They are a great way to ensure that you have written requirements to cover the system's behavior with all logical combinations of conditions. Complex logic often leads to missing requirements because certain combinations of ANDs, ORs, ELSEs, and NOTs were overlooked. Decision tables and trees are particularly good techniques to spot exceptions whose handling hasn’t been specified.

Test Cases

Functional requirements describe the behavior of the software to be built. Test cases describe ways to determine if the correct requirements have been implemented properly. Functional requirements and test cases represent two complementary ways of thinking about the software system. The first is from a constructive perspective (let me describe how to make it), and the second is from a destructive perspective (let me try to break it).

One school of thought maintains that detailed written requirements aren’t necessary; user acceptance tests provide an adequate description of what needs to be built. I prefer to think of specifications and test cases as being complementary views of the requirements. Thinking about the system from both perspectives often reveals inconsistencies and gaps in the BA’s and user’s knowledge.

Prototypes and Screen Designs

When prototyping, the BA is taking a tentative step from the requirements domain into the solution space. A prototype is like an experiment. It tests the hypothesis that the requirements you have developed to date are accurate and complete. Most people find it more insightful to work with a prototype than to read through a long list of functional requirements. A prototype serves as a tangible first cut at some portion of the possible product.

A low-resolution prototype, such as a wireframe, provides the gist of the proposed user interface, whereas a high-resolution prototype presents detailed screen designs. However, even a detailed visual prototype does not depict the details hidden behind the presentation layer. A prototype doesn’t show input field interactions or describe how the system processes input stimuli to produce output responses. As with analysis models, a prototype is a useful but insufficient means of “documenting” requirements; you still need to record the details somewhere.

Tables and Structured Lists

If multiple requirements are worded similarly except for a particular change from one requirement to the next, consider grouping them in the form of a table or a structured list. Grouped requirements are more maintainable because a global wording change need be made only once. This is more concise than writing out all the individual requirements in detail, and the differences between the similar requirements will be obvious. For traceability purposes, each item in a list should receive a unique identifier. Following is a set of similar requirements from an actual SRS, shown in the original style (bulky, repetitive, and eye-glazing) and then as a much more compact structured list. The list form more efficiently communicates the same information and still provides a unique label for each requirement.

Before:

SGML.Insert.23: The product shall provide a facility that will insert SGML data corresponding to signature block formats selected by the user from among a set of available boilerplate signature blocks.

SGML.Insert.24: The product shall provide a facility that will insert SGML data corresponding to leaveout formats selected by the user from among a set of available boilerplate leaveouts.

SGML.Insert.25: The product shall provide a facility that will insert SGML data corresponding to caption formats selected by the user from among a set of available boilerplate captions.

After:

SGML.Insert: The product shall provide a facility that will insert SGML data selected by the user from among a set of available boilerplate formats for the following:

.23: Signature blocks

.24: Leaveouts

.25: Captions

Mathematical Expressions

Mathematics provides a precise, concise, and unambiguous language for represent certain types of knowledge, particularly that associated with performing computations. Some types of computational information are better represented in the form of tables. Two examples are interest rates as a function of investment bond term and discount percentages applied to volume purchases of a product.

Always keep in mind that specifying requirements is a communication process. Every BA should develop a rich toolkit of techniques for representing information effectively. If natural language is the best technique in a particular situation, fine: use it. But first ask yourself whether some other method, either by itself or in conjunction with the text, will do the job better.

Contine on to article # 4: Selecting Appropriate Requirements Views

Author: Karl Wiegers is Principal Consultant at Process Impact, www.ProcessImpact.com. His interests include requirements engineering, project management, peer reviews, and process improvement. His most recent book is a memoir of life lessons titled Pearls from Sand: How Small Encounters Lead to Powerful Lessons (www.PearlsFromSand.com).