Documenting Acceptance Criteria using process diagrams
In the previous post, I spoke about documenting user story acceptance criteria using text. While text is probably the most widely used medium for communicating requirements, it is often less efficient than other means.
In this article, I want to speak about more visual formats for spelling out requirements and acceptance criteria. I will primarily focus on process diagrams (BPMN) and flowcharts.
TL;DR the key argument I am making here is that a process diagram or a workflow chart visualizing at least a happy path and alternative flows of a process being implemented/changed through software is probably one of the best investments a product manager, PO, feature lead can do to prep the team for a new feature.
First of all, why use anything other than text?
The answer is probably obvious: a picture is worth a
A month or so ago, I was working with one of the lead engineers on requirements for a relatively small but scenario-rich feature. Initially, I prepared requirements in the textual format (using “given when then” technique) and sent the document for the engineer’s review. He diligently reviewed it and came back with questions that we then went through.
I probably spent 4–6 hours preparing the document, it took him 30 min to an hour to read through and prepare questions, and then we spent another hour in a discussion. Overall, we are talking about a full day of work spent on documenting requirements.
Then, an idea came to me. I suggested I would revisit the feature and describe it using diagrams. It took me probably 2 hours total because by then I had a pretty decent grasp of the workflow and the topic.
Here is what the two formats looked like.
Textual representation
Diagrams
When I shared the diagrams with the engineer, he was not speechless of course but he admitted that the visual format worked a lot better as it reduced the cognitive load needed to go through different scenarios in texts and then analyze them one by one. What else helped was calling out the new functionality explicitly. To do that I color-coded the parts of the flow that changed or were added in green. Essentially, the engineer could not only understand the overall impact faster but the scope was also clearer.
I am not trying to say that diagrams SHOULD replace text as requirements being a more efficient and time-saving format. Often enough, the two come hand in hand. Furthermore, the work to spell out acceptance criteria may help with revisiting the overall flow.
What I am however arguing for is documenting the overall flow before going down to very detailed requirements statements. Doing this will help you identify more scenarios to consider and then will simplify managing new changes to existing processes if such a need arises.
In cases of smaller features (such as the one shown above), documenting the scope using the diagram could probably be sufficient however in more complex cases both text and some visualization would probably be essential. The diagram helps with understanding all scenarios at a glance that an engineer should keep in mind when designing the solution while textual representation helps with providing very specific answers during implementation.
Alright, so when to use some sort of a diagram?
Any sort of project that deals with a user interface or implements decision-making logic (when to consider someone eligible for a loan or what pricing to quote) will likely benefit from a chart or a diagram of sorts.
This is especially true when the project/feature focuses on some sort of a form with dependent controls where a user is also not locked to a single data entry path.
To this day, I recall a feature I worked on a couple of years ago where I did not prepare any sort of a process diagram envisioning how users would be interacting with it to achieve their goal. That definitely caused a problem where an engineering lead having realized the number of open questions from developers implementing the experience stepped in to develop such a diagram. Having done that work we identified a number of edge cases I did not even raise earlier. That of course caused the feature estimates to grow at least twice and resulted in certain compromise decisions that we now have to revisit 18 months later. This of course means rework and opportunity costs of not being able to work on other features.
My rule of thumb is that a process/interaction diagram always adds value as it gives clarity regarding inputs, needed interactions, and outputs of a process or a flow being implemented.
As for instances where it may not be worth the time and effort spent on it, those are probably limited to very small changes in existing established flows that already are well documented or known.
How good should a diagram be?
This is where I have seen and heard very conflicting feedback. On one hand, a diagram is a model and all models lie. On the other hand, people create diagrams to achieve specific goals. As long as the goal is to clarify, articulate and reach a conclusion on the behavior then the main requirements for a diagram must be completeness, unambiguity, and comprehensibility otherwise the risks of misunderstanding what is depicted are too high.
I have created more rigorous BPMN diagrams as well as simple flow charts and the answer depends on the context and seniority of the team.
In case the diagrams being created are a product in themselves and are a part of the service being provided to a paying customer, then the expectations from the diagram are much more stringent: the syntax of a chosen notation must be valid aka the diagram must be valid and the diagram probably has to be aesthetically pleasing (good looks sell better).
There is another reason for building high-quality valid process diagrams — in case the organization plans to implement the defined process using BPM software tools. To do that diagrams of course must be valid. I however have never worked on a project where that was the essential use case for preparing process diagrams and hence can speak to this only theoretically.
If you liked what you read here, please clap, comment or start following me on Medium
