Write good epics

December 12, 2023

As a project grows, soon enough a big list of tasks can become overwhelming. To organise this work we often turn to epics as a way to group similar tasks together.

Done well, epics can help:

  • Reduce the cognitive overhead of trying to hold every task in your head at once
  • Give the team a clearer understanding of priorities
  • Provide a language to talk about different parts of a project
  • Make it easier to communicate progress with stakeholders
  • Open discussions around launch milestones

But there is an art and science to the epic, and done badly they can add overhead while providing little value to your team and stakeholders.

Reduce cognitive overhead

You’re starting a new project, you’ve reviewed the requirements and the designs and now you’re creating tasks. It starts out simple enough but by the end of the session you have a list that goes below the fold!

It becomes impossible to hold all of them in your head, plus if you squint they all start to look the same.

Grouping the tasks brings calm to the chaos. It helps satisfy our working memory limits and makes it easier to locate that task you’re looking for.

🍔 Let’s take a look at an example. Our delectable side-business, thoughtburgers (home to the tastiest and most thought-provoking burgers!), needs to change their payment provider because their current one is having too much downtime. They spin up a project team and start planning out the work:

List of tasks as they start planning the project. Can quickly feel chaotic… 😳

- Make payment using new provider
- Handle 3DS
- Use saved payment method
- Refund orders from Admin
- Save payment method (during payment)
- Ability to switch between old and new provider
- Transfer tokens from old to new provider
- Automated refunds
- Remove saved payment method
- Payment reliability metrics
- Notify on Chargeback
- Save payment method (standalone, from account area)
- Ensure old compatibility once tokens migrated

Grouping the tasks into epics. An orderly calm… 😊

One-off Payments - Make payment using new provider
- Handle 3DS
- Payment reliability metrics
- Ability to switch between old and new provider
Saved payment methods - Save payment method (during payment)
- Use saved payment method
- Remove saved payment method
- Save payment method (standalone, from account area)
Refunds - Refund orders from Admin
- Automated refunds
- Notify on Chargeback
Migrate saved payment methods from old provider - Transfer tokens from old to new provider
- Ensure old compatibility once tokens migrated

Clarity around priorities

Epics give you and the team a clearer focus on what should be done first. It allows you to have easier conversations when priorities get blurry.

“We’re focusing on One-off Payments right now and this refunds task we’ve decided to work on doesn’t really fit. Maybe we should deprioritize it so we can complete the epic first.”

Common language

In the spirit of DDD’s Ubiquitous Language, epics give us a common language to talk about various parts of a project. They map a project out into its core components.

Plus, abstractions make for easy shorthand: Saved payment methods is a great shortcut for referring to all the tasks within it without having to list them all every time.

Communicate progress

Ever start talking about the progress of tasks with a stakeholder and see their eyes glaze over? Typically this occurs because we’re not modifying the level of detail to fit the audience.

Tasks are noisy and contain a lot of detail. But epics provide a great way to communicate progress at a higher level. A level that leadership & stakeholders care about and can easily understand.

❌ Bad: “We need to handle 3DS and reliability metrics, then we’ll look at saving payment methods, using saved payment methods, being able to remove saved payments methods and being able to add a new payment method from your account.”

✅ Good: “We’re on track to complete One-off Payments this week, then we’ll move on to Saved payment methods.”

Here’s another example which shows two ways of representing the same data:

1. Tasks represented on a Kanban board

  • Audience: Project team
  • Frequency: Daily

2. the same data represented as epics

This is an aggregated view of the progress shown for the tasks.

  • Audience: Stakeholders, leadership, and the project team itself
  • Frequency: Weekly

Discuss launch milestones

Epics are a great lever to discuss what should be in or out of a launch. Coming back to our friends at thoughtburgers, they want to switch payment providers fast because downtime means no burgers in bellies and that’s not a world we should live in.

What do they really need to launch? They need some way to process refunds but does it need to be automated? And do they need a slick chargeback notification at launch (the payment provider will let them know about them anyway)? Let’s refactor their epic.

From the original:

- Refunds
  - Refund orders from Admin
  - Automated refunds
  - Notify on Chargeback

Let’s split it in two so we can launch earlier:

- Refunds Phase 1
  - Refund orders from Admin
- Refunds Phase 2
  - Automated refunds
  - Notify on Chargeback

I couldn’t think of a better name, so I went with the basic “Phase 1” and “Phase 2”. Don’t be afraid to make the change even if you know the name isn’t great. It’s still progress.

After a good night’s sleep and a flash of inspiration we settle on some clearer common language:

- Manual Refunds
  - Refund orders from Admin
- Automated Refunds
  - Automated refunds
  - Notify on Chargeback

Separating the epics gives a concrete name to each decision that needs to be made. It makes it easier to talk with stakeholders and agree what’s in and what’s out.

“We definitely need Manual Refunds and we’ll work on that soon, but do we really need Automated Refunds for launch?”

But let’s not stop there. What about the epic to Migrate saved payment methods from old provider? This is certainly a usability delight, but do we need it? Is it such a hassle to ask users to re-enter their details one time? Perhaps we leave this till last with the option to drop it completely if we want.

Common pitfalls

So you believe in the benefits of grouping things. But how do you make sure you’re grouping the right things, in the right way, in the right groups?

Because failure is the best teacher, let’s look at how to write some terrible, bad, no-fun, horrible epics and note the strategies to avoid them.

The catch-all grouping

Our brains love to categorize. But sometimes the first, seemingly obvious, category is not the best one.

🍔 Let’s revisit our friends at thoughtburgers (home to the tastiest and most thought-provoking burgers!), who need to change their payment provider.

Take the following set of tasks:

- Make payment using new provider
- Use saved payment method
- Refund orders from Admin
- Save payment method (during payment)
- Payment reliability metrics

It is very easy, almost natural, to group them like so:

- Front-end
  - Make payment using new provider
  - Save payment method (during payment)
  - Use saved payment method
- Back-end
  - Refund orders from Admin
  - Payment reliability metrics

But this is a mistake. Grouping horizontally, in this case by technology layer, prevents most of the benefits we expect from epics.

These horizontal-black-holes suck everything into them. What seems reasonable at first slowly grows until they become meaningless. Let’s demonstrate by introducing a few more tasks:

- Remove saved payment method
- Save payment method (standalone, from account area)
- Automated refunds
- Notify on Chargeback

And now we group:

- Front-end
  - Make payment using new provider
  - Save payment method (during payment)
  - Use saved payment method
  - Remove saved payment method
  - Save payment method (standalone, from account area)
- Back-end
  - Refund orders from Admin
  - Payment reliability metrics
  - Automated refunds
  - Notify on Chargeback

Everything naturally fell into the existing epics, so they must be the right groups, right!? Multiply this scenario by the size of a real project and it should be obvious how this approach is far from ideal.

When projects never seem to end and scope just keeps increasing, this is a big factor why.

Special shoutout for the Admin

Another classic example is the “Admin” epic. The admin area is a separate vertical slice, but it’s not a function or an outcome. What’s the actual problem or feature?

It’s fair to say that the Admin area typically serves a different user and so there is probably an epic that represents these users lurking somewhere. But the trouble with a generic “Admin” epic is

  • It becomes a catch-all blackhole, as discussed above
  • It restricts our ability to discuss launch milestones. If everything to do with the Admin is in the Admin epic, at what point can you launch?

As an example, Refund orders from Admin triggers our pattern matching for “Admin” but the better grouping is around refunds.

Once an epic, always an epic

Once created and communicated publicly, there can be an inertia to epics. A resistance to change. A feeling perhaps that the cost is too high to change it now.

But as we learn more about a project, the domain, user needs and requirements, our understanding and the impact to priorities evolves. Epics should be no exception. Nothing is set in stone and everything can change!

Tasks can become epics. Epics can become projects. Orphan tasks can identify new epics and we can shuffle things about!

This is especially true of smaller projects. A project that feels like one feature and therefore one epic. After all, we only want to group vertically! Let’s look at an example:

🍔 thoughtburgers want to display the nutritional information for each of its menu items in its app

- Project: Nutritional information
  - Tasks
    - Nutritional information per menu item
    - Detailed nutritional info on-tap
    - Nutritional guide in account area

Seems simple enough. But then, someone asks, what about when you customise a burger? Like when, heaven forbid, someone removes cheese! Should the nutritional information dynamically update? Well let’s just add another task:

- Project: Nutritional information
  - Tasks
    - Nutritional information per menu item
    - Detailed nutritional info on-tap
    - Nutritional guide in account area
    - Dynamic nutritional info based on customizations

But as the team looks into it they discover it’s more complicated than first thought. The data for nutritional information per customization doesn’t exist and isn’t easily integrated. Now the scope has greatly increased and it’s blocking the team’s ability to launch.

Epics to the rescue!

- Fixed Nutritional information
  - Nutritional information per menu item
  - Detailed nutritional info on-tap
  - Nutritional guide in account area
- Dynamic Nutritional information
  - Dynamic nutritional info based on customizations

This doesn’t really change anything but it allows the team to talk in clear terms about what they’re focusing on and going to launch, while also being clear on what can come later.

The epic epic

Sometimes you create an epic, or are given one, that as you start to plan out the work, you realise is too big.

You feel this when you start reaching for some groupings between your epic and tasks.

But you may feel restricted because you already have an epic and an epic groups tasks. Bah! As the great Curtis Mayfield says:

Move on up!

If you need another grouping between what you already have, do it! It will help you plan better and it will make communication easier.

If the tool is getting in the way and won’t let you create the hierarchy you need, you can even just prepend the name.

Do what you need to do to create those groups!

Unnecessary indirection

Sometimes, the adherence to creating epics can make a project worse.

A 1-1 mapping of epic to task is a smell worth sniffing. Occasionally the task can be so different that it makes sense to have an epic just for it. But oftentimes it hints that things are amiss.

If a project is small enough to be solved with just a few tasks, forget the middle management of epics. The layers and groups only matter when they help not hinder.

If the shoe don’t fit, don’t force it!

Best practices

Finally, because repetition is memory’s friend, let’s explicitly cover off some best practices for creating and managing epics.

Be zen

The best way to write good epics is to not write epics at all. Don’t try and force yourself to create epics from the outset. Start with your tasks and as you create more, some epics will naturally form.

Of course, sometimes the top-down approach of creating Project > Epics > Tasks works great. But don’t stare at a blank page trying to create the perfect epics from the outset. Go with the flow and groups will appear.

Know the epic name or grouping isn’t ideal? Create it anyway. Don’t be blocked by idealism. But acknowledge that it probably needs to change and bring it up during the next planning session.

Epics live!

Now (and this is the most important part) don’t stop and be content with your “completed” epics. Review them regularly as part of your planning sessions. Epics are not set in stone. They can and should evolve. New epics will be revealed, tasks can be moved between them, orphan tasks will find a home, and old epics can be trashed. Some tasks may even morph into their own epic and that’s ok!

Group vertically

Beware the catch-all grouping! Of all the benefits that epics should give you, grouping poorly, horizontally, nets you none of them.

Much like we prefer to break our tasks into vertical slices, we should do the same with epics.

Group vertically by functionality or outcome instead of horizontally (I’m looking at you, front-end and back-end). Then bathe in the benefits epics bring you!

Name vertically

Naming and grouping are two sides of the same coin. But it’s important to remember that the name we pick can communicate a lot or a little.

  • Is the epic name focused on functionality / outcome, or is it talking about a technology layer?
  • Will stakeholders understand what the name means?
  • Do all the tasks fit or can you launch without something? Should we split and sequence the epics?
  • If splitting an epic in parts, does the name of each convey the scope of each part?

If we take a task like “Refund orders from Admin”, maybe it starts its life in an “Admin” epic. But as we ask these questions we can let the epic name evolve.

Admin > Refunds > Refunds Phase 1 > Manual Refunds

Write epic epics

Within the complexity of any project there lies a tool to bring order. Group things, then give that group a name.

So give yourself the time. Think about epics. Take care of your epics. Write good epics. Your team, your stakeholders and your future self will thank you.