How “Best” to capture State Transitions in a formal software requirements specification

Question

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.

Answer 1

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?

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?

Answer 2

Only the very simplest software systems can be usefully specified:

• solely in English
• with one testable fact per sentence.

Most realistic software systems are going to have some user-level requirements that correspond to tens, hundreds or thousands of test cases. One example is where some external standard is referenced (e.g. 'must support all HTML 5 markup tags', or implement this standard internet routing protocol, or whatever).

This is where experience and analogy with hardware testing, even of digital electronics, can be misleading; no-one implements HTML 5 in hardware.

If you are not careful, you end up with a specification that has literally 10s of thousands of 'requirements'. Almost none of which the customer would have any idea of what they mean, in the unlikely event they were to read them. Perhaps easy to test, but that testing tells you little about whether it is correct, let alone fit for purpose.

So something has to be done, if you want to be able to deal with any system more complex than a toaster at a cost less than developing a fighter jet.

One approach is to keep the top level user requirements in English, but have them reference lower level specifications that may or may not be. So the requirement is 'you must follow this specification', where the specification can be an industry standard, another document, or a model. A model may well be displayed as a diagram, but would be understood by the tools you are using at a high-enough level to, for example, generate test cases. So you don't need to manage traceability manually.

Another is to have the English specification automatically generated from a model; this is kind of pointless, but very straightforward to do. It may even be the best approach for systems that are generally trivial but have just one complex area.