Using State Diagrams to Improve Communication Between Humans

A few months ago, I found myself having a frustrating conversation with a Haven Life colleague, Josef, about insurance premium payments. As a Software Engineer (SE), I was trying to design a solution to cover some corner cases around failed payments (i.e. bounced checks). And as Product Owner (PO), Josef was trying to explain the requirements.

I found myself unable to keep the half-dozen or so steps of each Formally Defined Use Case (FDUC!) clear in my head.

F DUCk?

As I considered one, questions about the others would intrude. At first I felt stupid, but halfway through the second (or third?) meeting to discuss the same set of FDUCs with Josef, I decided that we needed a different approach.

Fortunately, I had one already in mind.

Inspiration:

I had been fortunate enough to attend a talk about State Diagrams the previous evening at React NYC by Lucas Reis, who described using State Diagrams (as an SE) to work through the design of an Insurance Picker widget with a PO. Lucas credited the use of State Diagrams with improving both the speed and quality of the collaboration between People Who Code and People Who Do Not Code to design and build an Insurance Picker Widget.

What Are State Diagrams?

For the purposes of this blog post, I’ll consider a “subset” of what Computer Scientists consider to be State Diagrams which are composed (entirely) of:

Node

• States: each state is a bubble (technically a node) with a unique label

Arrow

• Transitions: each transition is an arrow with a unique label, pointing from one state to another (or possibly the same) state.

With some additional properties:

• There is exactly one “Start” state (representing the initial state of the system which we’re describing) which has no transitions pointing to it.
• Every other state (besides “Start”) has at least one transition which points to it.
• Any state which has no transitions pointing from it is called a “Stop” state; There may be several of these, or just one, or none at all.

State Diagrams Are Not:

• UML diagrams — UML is much more powerful and ambitious in scope; It essentially aims to express every kind of formal relationship. It also has a long learning curve; Not even all SEs really know how to use it! There’s absolutely no reason to ask a PO to learn UML.
• Required to follow any particular rules about colors or shapes. Larger diagrams may be easier to read if node shapes are aligned with state “type”. My decision to use green circles for “Start” and red squares for “Stop” in the below examples is arbitrary (but fabulous!).

So…?

I proposed using a State Diagram to represent one of the Haven Life FDUCs which Josef and I had been struggling to describe, and Josef agreed to give it a try. I expected this exercise to take a while, but after only an hour Josef wheeled over a whiteboard covered with (fabulous!) arrows and bubbles. We spent another half hour together walking through the diagram, and after adding some more states and transitions and adjusting a few labels we had a “document” which:

1. Succinctly captured all of the FDUCs which we’d been discussing (not just one), and
2. Called out a list of questions which we needed to settle before we could deliver the final product

Perhaps more importantly, the work became fun again! I love drawing bubbles and arrows; It reminds me of my salad days as a mathematician, and makes me feel like I’m doing real Computer Science. And I learned later that Josef had also been frustrated by “getting lost in the prose” of the FDUCs, and appreciated the State Diagram representation for its conciseness.

Following Through:

After capturing the whiteboard image on my phone (so we could erase the whiteboard), I spent another 20 minutes using the “Mermaid” markdown syntax to express the State Diagram in a chunk of text which could be version controlled via git and rendered nicely “inline” by GitLab.

Including the State Diagram in the source code made it straightforward to refer to the diagram from inline comments (very useful for documenting all the assumptions which code can safely make about the overall state of the system), and the markdown syntax is also handy for linking the State Diagram to other human-readable text in the source code (and potentially elsewhere, via permalinks).

I also found the State Diagram helpful when explaining the intended system behavior to QA, and remembering the intended system behavior when returning to the code a few months later to add new features.

An Illustration:

I won’t share the State Diagram that Josef originally prepared, nor any of the later versions which emerged from our collaboration. Instead, I’ll use a simplified & sanitized (toy) example to show how a State Diagram can suggest useful questions about the Problem Space.

Suppose an Insurance Policy is Issued and remains In Force for as long as Premium Payments are received in a timely manner.

Here’s how we might represent this in a (simple) State Diagram using Mermaid markdown syntax supported by GitLab (forget about bounced checks for now!):

NOTE: Using transitions to model the passage of time makes it natural to extract any clock dependencies into a service which handles all time-related events, e.g. a scheduler. This separation of concerns gives us a convenient and natural way to simulate scenarios involving very large (or small) intervals of time, but a correct design must capture all of the ways in which the passage of time can affect the behavior of the system. State Diagrams are a great tool for making such time dependencies explicit.

An obvious question suggested by the diagram above is: How long does it take before a Policy Lapses?

Here’s how we might refine the State Diagram to explore this question:

The new diagram (which puts all States associated with an active Policy inside a blue box labeled “In Force”) makes it clear that there are several ways in which the passage of time (and the flow of money) can lead a Policy to a Lapsed state. Where to go next with this example would depend on What Features Need to Work First, and (conversely) What We Can Ignore for Now.

When Are We Done?

Ideally, a sequence of (increasingly useful) diagrams would naturally be produced as Engineering and Product work through iterations of a design. When it is possible to walk through all Supported Scenarios using a State Diagram, then it has achieved sufficient “breadth”. Sufficient “depth” has been reached when we have captured enough detail to write a test for each path through the diagram.

Conclusion:

I believe State Diagrams have immediate appeal because they are visual, and enduring value because they are precise. This together with the simplicity of their construction makes them a natural tool for collaboration. My own feeling is that they can be particularly helpful when doing iterative design, where it is crucial to quickly identify information gaps and unknowns which may affect the design at each stage.