There is no single correct way to document specific requirements information. Every BA needs a rich tool kit of techniques at her disposal so that she can choose the most effective requirements view in each situation. In this article, adapted from my book, More About Software Requirements (Microsoft Press, 2006), I offer some ideas about how to make that choice.

Often, it’s valuable to represent information at both high and low levels of abstraction. The high level offers a big-picture perspective, whereas the low level of abstraction presents the nitty-gritty details. Certain audiences only need the high-level view, whereas developers and testers do need to see all those specifics, as well. An effective requirements analysis technique is to create an alternative view of the requirements from the initial set of information and examine it for problems.

Here’s an actual example. I once reviewed a requirements specification for a client who was developing the firmware for a device for testing integrated circuit components. The spec contained a long table that listed the various states this device could be in and what behaviors lead to changes from one state to another. Table 1 shows a portion of this table. I needed to know if all possible states were described and that the allowed state changes were all correctly specified. But how could I judge that? Missing requirements are hard to spot precisely because they don’t exist.

I decided to draw a state-transition diagram from the information in the original table, which appears in Figure 1. A state-transition diagram is a simple analysis model that provides a high-abstraction view of such a system. It shows the various states the system could be in at a given time (rectangles), the permitted transitions between states (arrows), and the conditions and actions that lead to each transition (could be written on the arrows if desired). Other conventions have similar notations variously called a state machine diagram, statechart diagram, or simply a state diagram.

Sure enough, I found some problems with this diagram, shown with the dotted red lines in Figure 1. First, the table contained no functionality to get to the Off state! That is, I expected to see an arrow in the diagram going from Shutdown to Off, but I found no requirement to make this happen. Also, the table didn’t mention the possibility of an error occurring while in the Running state. Thus, by creating this second view as an analysis tool, I identified a couple of missing requirements. Better now than later, I always say.

Table 2 suggests techniques that are appropriate for representing various types of information at both high and low levels of abstraction. Chapter 12 of my book with Joy Beatty titled Software Requirements, 3rd Edition (Microsoft Press, 2013) provides more details on many of these methods and contains references to additional sources to learn about these techniques. Use this table to help you select appropriate techniques for documenting your requirements information.

[cta id=”7463″]