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.


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.

2 Answers 2


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?

  • We already capture the derived functional requirements, which I guess answers questions 3 & 4 from above. It is questions 1 & 2 that I am trying to figure out how best to capture. If I were to write a "textual" requirement based on the "Property Address Entered" transition then what else would it be other than "While in the Pre-Qualified State when a Property Address is entered then the system shall transition to the Submitted State"? We'd then have a section dedicated to Submitted State requirements. But how would the initiating action/transition requirement be captured? The diagram or text?
    – Dunk
    Commented Feb 25, 2015 at 16:32
  • @Dunk All four questions will yield one or more derived requirements (functional or non-functional). In the example of that transition from pre-qualified to submitted on input of an address, I would capture that as When in the pre-qualified state, the system shall accept an input of a property address and transition to the submitted state (and follow that with a reference to the business rules, a data dictionary entry, IRD, or ICD that defines what a property address looks like). If there is validation or transformation, those would be separate shall statements. Then I'd move on to the next.
    – Thomas Owens
    Commented Feb 25, 2015 at 17:06

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.

  • 1
    This doesn't make much sense. At every level, a requirement should address a single thing (be cohesive), along with the other qualities of a good requirement (clear, complete, consistent, atomic, traceable, testable). Of course, as you break down the system into smaller and smaller subsystems and components, you continue to break down these system requirements into one or more lower level, more detailed requirements. This is the whole point of requirements allocation and derivation.
    – Thomas Owens
    Commented Feb 24, 2015 at 23:16
  • 1
    I'm a proponent of model-based development when appropriate, but I fail to see how your last paragraph addresses the question. It sounds like Dunk doesn't have anything other than a state diagram. He needs to map this state diagram to requirements (either higher or lower level), design, implementation, and test artifacts. How does model-based design and model-based testing help with that? Ultimately, you still have a functional requirement that needs to be traced to everything that it touches.
    – Thomas Owens
    Commented Feb 24, 2015 at 23:18
  • I have much more than a state diagram, but I am trying to figure out the best approach for how to capture the requirements depicted by the "state diagram". The requirements derived from the diagram almost always just boil down to something like "While in State X, if input A is received then the system shall transition to State Y.". Which seems like it doesn't add much value beyond the diagram. However, when I get to State Y, then there are certainly requirements for what happens in State Y.
    – Dunk
    Commented Feb 24, 2015 at 23:29
  • @soru - It is probably just me, but I am as confused as Thomas with regards to what you are trying to say. I don't see the tie-in with the question I was asking. Maybe you can clarify the connection a bit better? I am a pragmatist, so I'm certainly not trying to get to "one testable fact per requirement" but at the same time the requirements need to be specific enough to know they've been met. So "The system must support HTML 5" most certainly requires more specification. Maybe version number, passing a specific test suite etc...
    – Dunk
    Commented Feb 24, 2015 at 23:44
  • @Thomas - You seem to understand exactly what I'm asking. Reading between the lines of your first comment, it seems like you are more supportive of Method 2, or do you also base the choice upon what best fits each particular project?
    – Dunk
    Commented Feb 25, 2015 at 0:01

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.