Software Requirements – How to Capture State Transitions in Formal Specifications

formal-methodsRequirements

Suppose you have a state transition diagram. What is the best way to "Formally" write requirement(s) that capture the state transitions depicted in the diagram. Over the years I have used two approaches and both work, but each time I work with new people there seems to be disagreements on how best to "Formally" capture the state transitions. "Formally" capture is required because traceability matrices are used that map to "Test Cases" and "Software Units (ie. Classes and/or Modules)".

Method 1

  • The system shall transition between states as depicted in Figure 1 XYZ Transition Diagram.

OR

Method 2

Look at the diagram and write a requirement for each transition.

  • Upon power up the system shall start in the Comms-Init State.
  • Upon establishing communications the system shall transition to the Initialization State.
  • (ie. A requirement for each state transition)

The benefit to method 1 is that it is one requirement and very easy to write.

The con to method 1 is that pictures don't work well with traceability matrices and it is more difficult to verify that you've covered all the transitions.

The benefit to method 2 is that each transition can be mapped to the explicit test cases and modules in their respective traceability matrices.

The con is that it is more work writing all the extra requirements and sometimes putting into clear and accurate words what the picture clearly shows is not as easy as it sounds. Also, the additional requirements seem to add more clutter as opposed to value, which makes reading the requirements less understandable rather than more.

While I suspect the answer in the simple case like I described is that it depends on the project or it doesn't really matter. The issue on my new project is that things are slightly more complicated (there are modes in addition to states that interplay). Thus, method 2 will potentially explode into a lot of requirements.

So I am asking the question because this is one of those "practices" that I have been doing without really knowing "Why". I don't generally like to work that way, so I am hoping that someone can point out valid reasons why one approach is "more proper" than the other and in the process I will learn the "Why", which will let me understand how best to tailor for the slightly more complicated scenarios.

Best Answer

I think the best approach to this would be to first provide a unique identifier to your state transition diagram. This will allow it to be referenced in downstream work. It would also allow your specific requirements to be explicitly linked to the figure, providing traceability between a visual model and a textual requirement, even if they live in the same document.

When you're creating textual requirements from the diagram, don't just translate the diagram to lines of text. In Visual Models for Software Requirements, the authors suggest asking four questions to derive requirements from a State Table or State Diagram:

  • What conditions are required for the transition to occur?
  • What action initiated the transition?
  • What is the output of the transition?
  • What actions or data transformations occur as a result of the transition?

State Diagram Example - Seilevel (http://www.seilevel.com/ba-resources/rml-requirements-visual-models/state-diagrams/)

The above diagram comes from the Seilevel website. The leadership of this company, Joy Beatty and Anthony Chen, wrote the book I linked to above. This example also appears in Chapter 23 of the book.

From a diagram like this, you can derive some functional requirements. For example, you know that your system shall accept a property address. There could be a data dictionary that describes that address's format that you can reference. I suspect that there would be some defined interface for the electronic transmission of an application. You could also reference an Interface Requirements Document or Interface Control Document that specifies the formats for inputs and outputs, if one exists. You can derive some roles and responsibilities from this diagram as well, that could go into a Roles and Responsibilities Matrix that can be created to say who can deny a submitted application. There could be business rules related to the application processing that can be functional requirements. If there is automated processing, you can derive non-functional requirements for the processing state, such as time.

Your "shall" statements would not just be an enumeration of this diagram. They wouldn't be things like "the system shall start in a prequalified state" and "the system shall transition to a submitted state when the property address is entered". Instead, you would use this as a tool to clearly see business rules and functional/non-functional requirements. It would especially highlight the requirements that are missing - what if you don't have a definition of who can perform the state transition from submitted to denied?

Related Topic