Should You Draw It? (Yes You Should!)

Overview

Diagramming is an excellent technique which is often overlooked. Here we take a look at the stage between User Story mapping and Acceptance Criteria (AC) creation to determine what are the benefits of producing strawman designs.

I’m going to make an assumption here before getting to the purpose of this article, and that assumption is that we have mapped out the user stories and have isolated a specific story to pick up.

The Story

Our story in it’s briefest form.. The system - whatever it’s purpose - holds account data for each user. As a user of the system I may wish to update my account details. For compliance purposes the system must retain details of my original account details, and whilst the migration away from the legacy system is not complete, we must also notify the legacy system of the account update.

Note: Many details which would have been surfaced during story elaboration have been omitted to keep the scenario simple.

At first glance this seems a relatively light ask of the team. But it’s this obvious simplicity which often catches us out. It’s when we are presented with ‘simple’ requests that our process discipline is challenged. There are a number of paths available for use to choose form at this point, with options for Dodger, Divers, or Elaborators.

The Options

Prior to embarking on the creation of code and test we can choose how to approach the ACs. There are 3 categories available for the team to identify themselves with.

The AC Dodgers - We’ve seen it far too often that for a ‘simple’ feature not even the acceptance criteria will be defined. An engineer who chooses this path is often confident in their own abilities yet they fail to observe the needs of their team members, and have most likely not thought about the larger picture - We’ll leave the AC dodging discussion here as it’s a rabbit warren and not the current focus. Needless to say this is not a recommended path.

The AC Divers - This is a common path trodden by many teams. Either individually or as a group, scenarios will be called out, expected response types and codes applied. Typically this approach results in an understanding amongst team members which is great, but it does not necessarily mean that the team has a consistent view of the implementation, nor does it mean that the team has agreed on the correct approach.

The Solution Elaborators - This group will elaborate on a high level design prior to creation of the ACs. A visual guide benefits this team and they have greater alignment on the shape of a solution simply because they can see it.

The team has decided they fall into the category of Elaborators.

The team sketch out a high level design, remembering that they are not aiming to dictate each line of code, this is a high level design, by which we mean that we intend to identify the components involved and the flow between them.

As a first pass a subset of the team puts together the following diagram:

At first glance this design covers the behaviour we are hoping to achieve, the legacy system is notified, the account change is audited. However, on closer inspection we can see there are questions to be asked about the asynchronous behaviour in some scenarios:

• updateAccount returns success, the client is happy, but the notification to the legacy system fails. What happens now?
• updateAccount returns success, the client is happy, but the persisting to audit fails. What happens now?

This looks bad, we now have a confused system. Despite reporting success to the client the internal state is inconsistent and far from success.

These questions have been asked because the team are working from a shared understanding, that understanding is the behaviour depicted by the diagram.

To address either scenario we could change the response to 202 Accepted and have the client make a subsequent request (or requests) to determine the final state, but doing so would mean additional complexity, and would achieve little more than informing the client there is a problem. We would still have failed to prevent the inconsistent state within the system.

There are issues with this design, but we’ve caught them early. Better yet, no lines of code were created before we found this issue.

Diagrams promote shift left

This is great, we have found issues before we have even written a single line of code, and this is the point. By creating a simple diagram all participants can now see how this part of the system was going to function, and by doing so we’ve caught issues before they’ve even been created. We’ve embraced the shift-left testing philosophy and found problems extremely early. If we give ourselves the opportunity to visualise the implementation, we can see these potential error scenarios much clearer than we could by dissecting a raft of ACs. These issues could so easily have been overlooked if we were just constructing ACs without the visual aide.

Had we dived straight into the ACs, there’s a high chance we could have implemented a poor solution. We’d run the risk of churn, defending and adapting to the poor design and mutating the ACs in a bid to correct the implementation, until eventually, we’d reach that point at which we realise that we need to stop and reassess the story.

However, that is not a problem for us now. The process of creating and reviewing the initial diagram highlighted these issues. Let’s take this feedback onboard and look at how we can improve.

Our second attempt looks much better, we’ve addressed the asynchronous issues exposed by the first diagram, whilst at the same time due to the transaction we’re in a position to provide the user with a clear success response on the synchronous call.

Draw your own conclusions

Diagramming a solution gives the team a shared understanding, and this understanding has been achieved by visually representing the solution. Having not taken this approach the team could easily have overlooked the asynchronous gotchas which had been highlighted via the diagram. Via diagramming we have seen that the team has increased understanding of the potential flows through the solution and more readily identify both positive and negative scenarios.

Achieving alignment and a deeper understanding of a solution, whilst also identifying and eliminating issues before a single line of code is written is a great outcome for any team.

The question now being asked is not, ‘Should I draw it?’ but now it becomes, ‘Why would I not draw it?’

---

View this article on our Medium Publication.