If you’re at all familiar with the software development lifecycle, you have undoubtedly come across at least a user story or two. I would wager the content, quality, and even nature of those “stories,” however, has varied significantly across projects, teams, and even “authors.” Why is that?
Well, for a hint, let’s look at a standard definition within the context of software development:
“A user story is an informal or natural language description of a piece of work that needs to be done.”
Simply put, it is an extremely broad definition and, as a result, story content is going to vary significantly across all of those factors mentioned above—author, project, and team. Now, is this a problem or an advantage?
I would argue that it’s a bit of both. A user story’s open-ended nature mostly works to its advantage. When done well, being open-ended allows user stories to tailor fit the language and content to specific use cases, while being readable to team members and external users. Many issues surrounding user stories come from those first three words, “when done well.” For one, it’s often not easy to describe a particular piece of work in a way that informs a technical role about what to do while, at the same time, broad enough for a non-technical role, such as a product manager, to understand the task, and a semi-technical role, like a QA tester, to understand how to test it. Additionally, if the story content is too broad, it becomes difficult to know what to include or what structure is best used for a given context.
To help combat all of this ambiguity, there are a veritable swarm of user story “formats” to follow in order to help guide the writer. These formats are a good starting point and help move stories to their ultimate goal (quantifying work) but are hardly flawless. To help illustrate, here are a few examples:
- As a <role>, I can <capability>, so that <receive benefit>
- As <who> <when> <where>, I want <what> because <why>
- As a… who wants… so that…
Each of these frameworks prompts the writer to ensure key details are included in the story. Who the user is, what they want, and why. This, at a minimum, should ensure that the story has at least some information that explains what needs to be done. That said, issues can arise when following these formats strictly as they are often prone to miss something. To make matters worse that something isn’t always the same. In other words, specific context can radically change what information you need to provide.
For example, let’s imagine a service running in the background to ensure all data is in the same format. At no point do users directly interact with the service. It just runs in the background without their input and makes sure everything is working smoothly. Let’s say there will be another type of data that will need a brand-new conversion made to it. If you strictly follow a format that cares about a user doing something, you’re not going to talk about the key aspect of the work needed:
As a user of the system,
I can keep using the data the same way,
So that the system continues to work.
There are many issues with this statement, but as far as following the format, there are a few specific problems. The section “As a” is supposed to help narrow down where the impact of the change is occurring and simply saying “a user in the system,” while accurate, doesn’t tell the person reading the story where the change is taking place (which would be at the point of data ingestion). The second section “I can” should illustrate what is being changed. Again, while the description is accurate, it fails to convey what precisely is being changed (the data ingestion flow). And lastly “so that” should indicate the “why” of the change. In contrast to the first two problem lines, this one is fine as is. The goal or why in this case is relatively straightforward and indicates the reason.
In my opinion, there are two options for fixing the issues. One can either treat the data ingestion flow as a user itself to help highlight the where and what. Or the description can be left as is and instead much more specific details can be provided in the acceptance criteria. As with real-world scenarios, the issues in large part stem from the fact that the example is somewhat vague and can be serviceable with more details.
The example below gives a better scenario in which our user story format works better:
As a project manager,
I want to be able to select the forecasting type,
So that the correct formulas are applied at my discretion.
In this example, we have a more clearly defined user, a project manager, instead of it being “everyone.” The end goal is better captured as a function that can be provided through a dropdown or selection method. And finally, the justification is serviceable. As an aside, this would be a great example of when to include an additional section to further expand on the why (so that these project managers choose the forecasting type) that might not exist otherwise.
Neither example, however, discusses the acceptance criteria, which allows for additional information related to the conditions that must be met to be accepted by the user or system. The point remains just using “a format” is not going to make your user stories useful and complete. They are a starting point to keep things consistent and help with the most important purpose—making sure you communicate the work that needs to be done. Of course, user stories have a multitude of benefits: keeping track of time spent on a project, serving as documentation, providing mini message boards, grouping a set of technical tasks, and helping in various other ways. We will dive deeper into these different uses and consider their implications in a future blog about acceptance criteria!