Epics, User Stories, and Requirements

Table of contents

Let’s take this piece by piece: being agile changes little to nothing about the need to document requirements. It doesn’t matter what name or structure we use. We call them epics, user stories, or requirements. We use them within the context of operations, projects, or innovation. Documenting these structures — our needs, or how we plan to seize the opportunities we’ve identified — is fundamental to any initiative. And I don’t just mean this in the sense of communicating what we’re thinking to others; I also mean the process of documenting for the future. Documenting is a process that involves writing, and in doing so, often without meaning to, we end up structuring our own thinking better.

Some history to start with. Software development is today, and has always been, a huge communication challenge between people. Since the days of punch cards, programmers — those capable of creating programs for computers — and the idea people — those incapable of creating the programs, but full of good ideas for harnessing a machine’s computing power — have struggled to “understand each other.”

Requirements

Many tools have been created to solve this communication problem, and the basic concept behind them is known as a software “requirement.”

In systems development engineering, a requirement is a documented need regarding the content, form, or functionality of a product or service. It’s used in a formal sense in systems engineering , software engineering , and requirements engineering .

Wikipedia (April 2020) — https://es.wikipedia.org/wiki/Requisito_(sistemas)

Why Is It So Hard to Write Requirements?

There are many theories about why requirements are so complex. That said, to illustrate my point, I want to use a concept I’ve always found fascinating: Fred Brooks ’s conceptual integrity. It refers to the ability of a single person, or a very small group of people, to hold the entirety of a system’s, product’s, or model’s design in their heads.

In one of his books — The Design of Design — he lays out conceptual integrity with an example: think for a moment about who invented the light bulb, the telephone, the telegraph, or the airplane. In all those examples, it’s easy to name the inventor. But when the complexity of the system being designed grows substantially, it becomes almost impossible for a single person to hold the detail of every component in their head. At that point, maintaining conceptual integrity becomes a real challenge.

If the problem still isn’t clear, think of a book you’ve read and discussed with someone else. What are the odds that your mental image of the characters and their motivations is exactly the same as the other person’s? NONE! And we’re talking about books that run hundreds of pages.

A student once told me in class, while we were covering this concept: “the problem [with conceptual integrity] is that everyone else insists on thinking.” While I understand where that frustration comes from — the fact that different interpretations aren’t aligned at all can be maddening — we can’t defend the idea of “stop thinking.” What we’re actually after is exactly the opposite: we want every individual member of a team to think.

Collaboration or the Search for Someone to Blame

Another thing worth considering when deciding which tools to use to facilitate communication between “the people with the ideas” and “the people who can build them” is the magnitude of that collaboration. In other words, how much collaboration and trust exists between the members of a team and within an organization.

Trust requires psychological safety among the members of a team and within an organization or company. Psychological safety is a term coined by Amy C. Edmondson, a professor at Harvard Business School, and it shapes how we communicate — especially during creative processes or the building of new solutions.

https://www.youtube.com/watch?v=Ms4FbDYXYoM

In an environment with low psychological safety, team or work group members don’t trust each other. When a threat shows up — a problem, a mistake, a misunderstanding — individuals look to “offload responsibility” onto someone else. If this happens regularly, requirements turn into the “contract” that governs the relationship. The result is documents that grow bloated with details and explanations meant to moderate the conversation between the parties involved — almost as if trying to “document” whose fault it will be if something goes wrong.

Use Cases

These are the step-by-step documentation of a user’s interaction with an information system. Describing that step-by-step, click-by-click, moment-by-moment interaction gave rise to Use Cases. A UC — Use Case — holds detailed information about the interaction flows a type of user (an Actor) goes through, almost always laid out as a conversation:

I think you already get the idea. This conversation between the user and the system also got layered with:

One of the best books for writing good Use Cases came to me by way of a great entrepreneur — Alex Torrenegra — back when I was still trying to make a living writing code: Writing Effective Use Cases , by Alistair Cockburn.

Pros

Cons

Innovative Environments for User Stories

In higher-uncertainty environments, where requirements aren’t clear, having a detailed level of documentation can be difficult or simply impractical. To give an example, when we’re working on discovering or designing new products, defining requirements in that much detail can become a headache, or a real limitation for the team.

User Stories

To encourage participation from every team member and promote divergent thinking, new, much lighter documentation models emerged — geared toward fueling discussions that add value to the solution. eXtreme Programming (XP), an agile software development process born in the ’90s, proposed the use of User Stories (US).

User stories serve the same purpose as use cases, but they are not the same thing. They’re used to build time estimates for release planning meetings. They’re also used in place of a large requirements document. User stories are written by customers as things the system needs to do for them. They’re similar to usage scenarios, except they aren’t limited to describing a user interface. They come in the format of roughly three sentences of text, written by the customer in the customer’s own terminology, without technical jargon.

eXtreme Programming (April 2020) — http://www.extremeprogramming.org/rules/userstories.html

Unlike Use Cases, US promote several things:

  1. Focusing on the goal (the opportunity or need to solve) rather than the how
  2. Keeping focus on the goal promotes innovative solutions
  3. It means users, customers, and stakeholders don’t need to know the system in order to contribute ideas or request new functionality
  4. Conversation, discussion, and debate about how to solve or complete a US are welcome — something that can happen with UCs too, but almost always feels more like an “explanation of the flow” than a genuine discussion among equals

Pros

Cons

If you want to learn more about writing good user stories, I’d recommend reading Mike Cohn’s cornerstone book on the subject: User Stories Applied . I also want to give a well-deserved shoutout to two Colombians (Lucho Salazar and Jorge Abad ), who did excellent work with their book Historias de usuario: Una visión pragmática .

Agile Modeling

Agile modeling refers to the use of other instruments and tools for documenting requirements — mostly for software. You can think of them as a kind of “extension pack” for frameworks like XP or Scrum . In my experience, the most useful complementary tools these days are:

Scale and Breakdown, Beyond User Stories

That said, using a single instrument within the Backlog — or describing everything at the same scale — is inefficient when that same instrument needs to hold different time horizons. In other words, the Backlog includes requirements that are so clear and so important they need to be executed and completed in the next few weeks, and it can also include items that are still barely vague ideas.

These “notes” in the Backlog feel more like a “reminder” for a future discussion — in my very personal opinion, and maybe influenced by the management software tools out there, you should always jot down every idea and concept with the potential to become real in the Backlog, rather than relying on human memory.

As a result, the magnitude of the effort and the complexity of an item within the Backlog can encompass many requirements — in the form of stories, use cases, or simple tasks — and here’s where I part ways with the radical purists. In their eagerness to name different scales of detail and magnitude, and to make clear that certain items need further breakdown, concepts like Epics, Features, and Capabilities were created.

Practical tip: Use the terms Epic, Feature, and Capability however you like, but don’t swap them around, to avoid confusion. You can use one, several, these plus others — don’t overthink it. Just give each term its own context and its own specific use.

Epics

One excellent idea from the Scaled Agile Framework team was defining specific purposes for each instrument — and also goals within the planning and execution time horizons. It’s not the only way to do it, but it does strike me as the best one (so far) for telling each scale apart.

Within this framework, epics are instruments for defining portfolio investments — for marketing reasons, and to distance themselves from the ever-lagging PMI, they decided not to use the word “project.” Epics, then, are portfolio or program components that include validating technical or business hypotheses — similar to an Agile Business Case. They insist epics and projects aren’t the same thing, but just as I have my personal disagreements with “PMI philosophy,” I also have them with “SAFe philosophy.”

Within an Epic, we can cover a lot of ground — some of it aimed at reducing risk, some at enabling our organizational or technical capabilities, and some 100% aimed at meeting strategic objectives.

Features

That said, an epic defined at this scale can feel very far removed from the work agile teams actually do. That’s why we need intermediate instruments to connect the strategic scale with the operation and delivery of that business value. This is where, much to my chagrin, they reached for terms closely tied to product development: features .

Features do two things: they’re a high-level requirement, sitting somewhere between Epics and Stories, and, as a result, they also represent a set of Backlog items that sits closer to the team — although SAFe defines other, higher-level backlogs too. What’s interesting is the timing relationship they try to preserve between stories and features.

Capabilities

In SAFe, there’s an additional aggregation instrument known as a capability, whose most notable difference from features is that it’s completed through the work of different ARTs — a term for a large-scale agile team focused on a product, service, or Value Stream.

Planning Instruments

Remember, Backlog items are instruments for identifying value and maintaining alignment between purpose and delivery — a concept gaining traction in the world that promotes “business value flow.” In the same way, these items are very useful for establishing time horizons and, whether we like it or not, business milestones.

Having items that represent different scales of effort is very useful for establishing a delivery cadence. To take an example, we can look at the Scaled Agile Framework’s proposal:

Conclusions and Considerations

The challenge is the same one: maintaining conceptual integrity among stakeholders — those wonderful, diverse, and scattered human beings — while facilitating and promoting the development of “the best possible solutions” — technically, economically, functionally, and in a way that’s easy and pleasant to use. There are instruments that limit creativity and divergent thinking — very useful for solving complex problems where teams lack the experience and/or knowledge, or where it’s simply impractical to propose different solutions or invite interpretation, like advanced calculations with data, reports, and heavily regulated business processes. There are also instruments that promote divergent thinking and innovative solutions, which help create new and better products, and that establish mental alignment mechanisms — like Agile Personas — to strengthen conceptual integrity.

These instruments, like user stories, are also useful depending on the team’s maturity stage and how well the members already know the system. Imagine a group of “newcomers” with no prior experience trying to design a system within an organization with strong design constraints or technical limitations — like legacy systems — using nothing but user stories. It would be frustrating!

On the other hand, imagine an experienced, tightly-knit group of colleagues trying to solve a challenge by following the steps of someone who isn’t even with them. Boring! We always need to balance capabilities against the challenge, and these instruments can be useful at every stage of every cycle.

https://www.youtube.com/watch?v=0Ky83at0CBI

Other instruments only exist to let us handle different scales of effort and/or time, like epics and features. They’re useful for managing multiple teams at a high level and communicating intentions, purposes, and value objectives.

As a final thought, I’ll leave you with this short video on the concept of Conceptual Integrity. Nothing as deep and radical as Amy’s video.

We’ll surely see new ways to communicate and document our needs in the future, and I hope to be there to use them and make the most of them.

· 12 min read
../