Let’s talk about the Agile Manifesto for a second. Of the four main values espoused in the manifesto, one of the most commonly misunderstood is the idea of prioritizing “working software over comprehensive documentation.” It sounds nice in theory, but in practice it often leads to developers and coaches downplaying documentation to an unproductive extent. Sure, working software should be the goal—but you do need some documentation in order to make that happen.
How does this manifest itself in the real world? One big way is the creation of less-than-useful user stories. Think back to your last Agile project—were your epics divided into stories that gave you enough context to actually create all of the individual tickets to get the relevant functionality up and running? Or was there a lot of ambiguity and guesswork involved? We’re guessing that for many of the folks reading this article, it was closer to latter than the former.
We’re also guessing that sometimes, when your stories are non-specific or leave a lot of room for interpretation, it feels like evidence that your Agile framework is working. You’re prioritizing people over processes, and you’re not getting hung up on documentation, right? This might be true if vague stories were a good way to generate working software, but more often than not they’re an impediment to successful development projects.
That raises an important question: how can you improve those and get your software working more easily?
How Do User Stories Fit into a Scrum Framework?
First, let’s back up a step and give some quick background so that we’re all on the same page: when we talk about stories, we’re talking about smaller components of larger epics and initiatives that keep the focus on the end-user of the software. Mike Cohn, in his book User Stories Applied, describes the now commonly used shape of a story: “As a [persona], I want [goal], so that [reason]." Here, the persona should reflect a user with a particpular use case that they’re interested in; from there, you give a sense of the action that user needs to take and the rationale behind it. This has the effect, again, of keeping the end-user’s needs in mind while giving your Agile team a clear image to coalesce around, which should ultimately yield more opportunities for collaboration and creativity.
But here’s the thing: there’s a big difference between “As a blog writer, I want a sortable table of blog posts that displays publication status, date, author, and campaign, so that I can easily organize my content calendar” and “As a planner I need dock-to-dock capabilities.” With the former, a developer could easily jump in and understand the requirements—especially if there were additional information in the body of the ticket (more on that in sec). With the latter, the creator of the story might know what it means, but in all probability not everyone else will. If a developer was assigned this story without the wealth of functional knowledge required to decipher it, that developer would be stuck grappling with the fact that the real requirements for this story reside only in the head of the person who originally created it.
Why Well-Groomed User Stories Are Critical to Success
The scenario above should give a pretty clear idea of why well-groomed stories are so important to Agile teams. When a story contains a clear, complete picture of what functioning code should look like, developers can easily jump in and contribute to the larger initiative. When the details are hazier, or they exist only in one developer’s mind, there’s no telling what could happen: the developer assigned to the particular story might have a completely different idea of what “dock-to-dock” means, or a completely divergent sense of who the intended user is and what their challenges are—this would result in time-consuming rework when the delivered functionality didn’t match the actual need. Or, the developer and the QA team could have different visions of what the story meant, meaning that the testing process would be full of false negative or false positives. Here, the result is the same as the previous example: a lot of rework that can threaten your budget and your time-to-market.
How to Create Stories that Result in Functioning Software
Now that we’ve seen what not to do, let’s look at a few important steps for crafting user stories that will actually keep your Agile teams on track:
1. Make the Implicit, Explicit
Like we said above, any context or requirements that only exist in the mind of the person who created the story is basically useless. All of the information that you think goes without saying (e.g. “obviously the user wants to be able to be able to control permissions so that writers can only edit their own posts,” or “everyone knows that logistics planners need to be able to sort projected freight prices by lane and carrier”), really does need to be said, so that your developers can all get on the same page about the features they should be building. Bear in mind that the ticket containing the story can include more than just the topline “As a [persona], I want [goal], so that [reason]” The body of the ticket can and should include not just an explication of the assumptions being made about the user and their needs, but also:
- A definition of what it means for the story to actually be “done.”
- Some background information on who the user persona is. Again, this should try to fill in information for people who might not already have functional knowledge.
- A sense of how the ticket slots into the larger sprint timetable (either through story points or an actual time estimate).
In this way, again, you’re able to get your developers on the same page so that they have a shared understanding of what features the user actually wants. This doesn't mean, by the way, that you need to gather all of your story requirements in advance (otherwise your Scrum framework would be in danger of turning into Waterfall), just that as individual stories are created they should be positioned in such a way as to facilitate delivery.
2. Idiot-Proof Them
Similar to the concepts we talked about above: the goal of being explicit isn’t to to dump a large amount of data onto your team—it’s to prevent miscommunication and incorrect baseline assumptions once developers start working on actual tasks and subtasks. Now, we take that a step further by striving to provide enough information that anyone with the right programming skills could walk in off the street, understand the requirements for the features that the user story discusses, and get started developing the right things. This might seem like too high a bar, but it’s actually a potentially value-additive step for two reasons:
- Code will often have to be integrated or validated across functions. This means that even if you write up your story in such a way that everyone on your team understands it, you could still run into disruptions if the QA team across the office is confused or doesn’t understand some of the requirements.
- Your capacity needs may increase over time—meaning that you could be in a position where you have to rapidly scale up your development team in order to meet a deadline. When this happens, you might pull developers from other teams within your company, you might hire some new people, or you might work with an outsourced team of developers. Either way, you’ll want to position them to contribute to your project as quickly as possible—which will depend on how easily they can understand your stories at a glance.
The second use case might seem like a less imperative consideration—but thinking about it early on is another way to avoid rework once the delivery deadline begins to loom.
3. Use Specific, Objective Measures
This tip is fairly straightforward, but it can make a huge difference—particularly once you make the handoff to QA. For the purposes of crafting stories that actually produce working software within a decent time-to-market, “the page needs to load quickly” is basically useless to you. Quick by whose standards? Quick relative to what? Because the metric here is subjective and not measurable, someone could easily turn in code that doesn’t meet the requirements because they have no way to verify what the requirements actually are.
By contrast, “the page needs to load in 2 second,” is specific, measurable, and objective. There’s essentially no room to misunderstand, and you can answer the question of whether it meets the requirement with a simple “yes” or “no.” The extra time it might take you to define these measures in the story creation phase will save you time and uncertainty once the sprint is officially underway.
4. Remove Ambiguity
We’re willing to risk sounding a little bit repetitive if it means that we get our point across and provide actionable information for Agile leaders and teams. So, we’d like to hammer home one last time that ambiguity in user stories is one of the biggest blunders that Agile teams can make. When you’re creating stories, it’s important to ask yourself: “Can this be interpreted in a different way from how it’s intended?” “Will the meaning of the story still be clear to someone who doesn’t work on the same components or in the same space that I do?” “Is there a chance that a developer could misunderstand some or all of the requirements based on how the information is presented?” If the answer to any of these questions is “yes,” it’s time to make some adjustments. Trust us, it’ll save time, money, and frustration down the line.
Learn More About Intertec’s Software Engineering and Support Services
Intertec specializes in building and supporting custom software for its diverse clients. Our experienced team of interdisciplinary professionals have experience at all stages of the software development lifecycle. Click here to learn more. Prefer a personal consultation? Go ahead and schedule a meeting with us here!