How to Document Status Flow in Your Application
During my career as a Business Analyst, I have seen a lot of confusing status flows. Sometimes it is about too many statuses and incomprehensible transitions between them. And sometimes it is that nobody in the project even remembers when and how the statuses’ changes are triggered. And sometimes it can be both.
If you struggle with understanding how the status flow works in this big application you were thrown into, or you are trying to document a flow that is getting more and more complicated every day — it’s high time to embrace it!
1. List all the statuses
The first task is to list all the statuses that are available in your application. Let’s see statuses for an e-commerce order as an example. For now, I will simply list all the statuses with their descriptions. I also have a column called Available actions, but I will keep that for later.
2. Prepare the flow diagram
With the status list ready, let’s head to drawing the flow diagram. I like to use the draw.io app, it’s easy and free, so you can play with it as much as you want to. First I will take care of the best-case scenario, that covers most of the statuses.
Now, let’s dig into the more complicated part. We are missing Returned and Cancelled statuses. We can also skip some statuses and go directly from Payment received to Delivered if the customer collects the order personally.
You can see that 3 statuses can lead to Cancelled, the Returned status created a small loop, and also you can go straight to Delivered from Payment received. That explains much more than a simple table where we listed the statuses above but still does not answer another question. What triggers the change from one status to another?
4. Describe the flow between statuses
The answer can be found in the flow table. You probably noticed that I had put numbers between statuses on the second diagram. The following table will list all these transitions, as well as the actions that trigger the change.
I prefer to emphasize which changes are manual, and which are automatic. In this way, you won’t be lost when filling in the Available actions column.
At this point, you should also be able to indicate some missing, unnecessary, or unclear statuses. In my example it is striking that transition (4) Awaiting payment — Cancelled is automatic, whereas (5) Payment received — Cancelled and (6) Preparing to send — Cancelled are manual. How can I know what caused the order to have Cancelled status? This is the weak point of the flow and needs a redesign.
5. Fill in the Available actions columns
In our first table with the status list, I left the Available actions column unfilled. Now it’s time to fix it. In our example, I imagine I will have an options menu for an order. The Available actions will be the list of all the options for the order in each status.
If you paid enough attention to the status flow table, filling the Available actions column should be quite easy. Remember, that only manual changes between statuses are actions — the automatic ones are triggered automatically, so obviously, you don’t need any actions for these transitions.
My example is quite easy and is probably missing a lot of statuses/transitions to be able to describe the e-commerce process well. In Available actions, you will probably want to have a lot of other options, that don’t trigger any transition between statuses — like Add a note or See details. It would be great to register them on the list as well, to keep track of all the possible actions that can be performed in each status.
It doesn’t matter if the status flow you want to document is simple or complicated. With the presented approach you will not feel lost in the sea of statuses. Write down the statuses, their meaning, transitions, and actions available for each of them. And you are ready to go!
