When Visual Models are Better than Textual Requirements (Part I: State Diagrams)

In this series, I show how different visual models can help you create better requirements. If you don’t want to miss the next installments, make sure to follow me on LinkedIn or subscribe to our infrequent updates entering your email to the right.

# # #

The ability to write high-quality textual requirements is a skill highly valued by many organizations, in particular the ones that have suffered the negative consequences of poorly defined requirements: project delays, cost overruns, expensive rework, dissatisfied users.

But visual models are also key to preventing misunderstandings and missing requirements as a business analyst specifies system behavior for an agile or traditional software project. A process map showing the sequence of steps, inputs, and outputs needed to handle a business process across multiple functions, a relationship map showing what information and products are exchanged among internal and external actors, a state diagram describing the behavior of an object over time — all these models can be extremely useful to facilitate the knowledge transfer about how a software application will support a business process, and uncover requirements that must be a part of the solution.

Let’s look first at state diagrams. A state diagram is a model suitable to when you’re trying to answer questions about the lifecycle of a business object: what states are allowed for it, what events trigger a change in the current state.

Example of state diagram depicting the states for the object “Contact” in an email automation application

The object (or data entity) can be anything that the business (and the information system that automates it) must keep track. For instance, a blog post in a content management system that can transition from “draft” to “published” and “deleted”, or a contact in an email automation system that can have the states of “subscribed”, “unsubscribed” and “deleted” (as in the example above), or a product in an ecommerce platform that can be in the states “in-stock”, “out-of-stock”, or “discontinued”.

Why draw a state diagram?

It’s possible to surmise the behavior of a business object over time analyzing requirements and use case descriptions. For example, one could gain an understanding of the contact object in a marketing automation system by noting how it’s handled in the requirements for User Subscribes to Mail List, User Unsubscribes from Mail List, User is Deleted by System When Email Address No Longer Exists. But if the state of the object is critical for the system (e.g., the business could get in trouble if contacts who unsubscribed from the company’s mail list are kept in the Active state by mistake), it’s helpful to be able to get the full picture of the object as it passes through the system.

Let’s say you’re writing requirements for a content management system. By drawing the desired states for blog posts (“draft”, “published”,  “deleted”), you could more easily identify all desired transitions (for example, not just from “draft” to “published”, but also from “published” back to “draft” to allow an accidentally published post to go back to draft where it can continue to be worked on). If your requirements didn’t account for this scenario, content managers would have to go through multiple steps to fix this mistake, copying the content to a text editing tool, deleting the published post, and creating a new draft.  The diagram would quickly highlight the missing transition to be incorporated into your requirements (“A content manager can revert a post from published back to the draft state to allow for more work to be done in a post prematurely published by accident.”).

What next?

Just reading articles or books about a business analysis tool or technique won’t get you far. To truly master the use of the technique, you must practice it in a context in which you receive expert feedback. Otherwise, you can end up like a senior BA who when asked to produce a state diagram to represent the states and transitions for gift certificates while participating of Crafting Better Requirements, created this:

Clearly the BA misused the term “state diagram” here.  “Purchase Gift Certificate” and “Redeem Gift Certificates” are not states of the object “gift certificate”. These are user goals that can be represented by use cases and business process diagrams. A valid state diagram for gift certificates would describe the states a gift certificate can be in (e.g., “created”, “delivered”, “partially used”, “depleted”) and what events would cause a gift certificate to transition from one state to another.

Luckily this senior BA made this mistake in a safe environment of a coaching program as opposed to in front of his manager and stakeholders at work. To avoid damaging your reputation due to flawed models like this at your job, see if you can enlist the help of a knowledgeable colleague to provide honest feedback for the diagrams you draw before you share them with a larger audience. Or take it a step further and do like the hundreds of BAs who decided to take their requirements writing and modeling to the next level by joining the Crafting Better Requirements program.

# # #

Read also Part II: Relationship maps and Part III: User flow diagrams