In grooming and backlog refinement in software we find ourselves breaking functionality into epics, which then have many stories, and - from here I like to break stories explicitly into behaviors, or at least acceptance criteria.

With stories classified into epics you may be able to, upon completion, see the larger business functionality, and where the foundational pieces hopefully set up technical earned interest for the next piece in line.

If we graph this it looks something like this:

Tickets and Epics

This forms a bit of a behavior layer cake, as the C4 model defines pure architecture decisions at various layers of abstraction.

The ecosystem around the epic determines, to some extent, the length of the epic

The epic should encapsulate the business changes, technology changes, security change (if applicable), and QA changes / work to safely deliver the software.

At the epic level we start seeing affects of the platform or developer ecosystem we’re running on: the road that provides smooth ability for customer journeys to be delivered.

How much does the existing code easily adopt to our changes, or have the business or technology use case advanced beyond the institutional knowledge / state encapsulated into the code. (aka: how much do you need to refactor things?)

Likewise, how much ecosystem related developer work do we need to do. Do we need to write CloudFormation to get some EC2 boxes up, have someone install Vault, build a container, hook up monitoring, etc? An organization in a stable growth plane ideally should have patterns around this: but maybe you’re not there yet!

In short: from a particular epic we should go down a layer to see the tickets in the story, and we go down into a story to see the behaviors.

If some work is larger than an epic

This common hierarchy of epic -> story -> behavior is best if it affects a single microservice, or maybe small clique, of a microservice herd. (ideally you have full stack teams enough that the backend and UI work can be done without a hand-off).

But for changes to a large percentage of the herd, it’s unlikely that just epics will contain all the information all stakeholders need to make correct decisions. Usually you’ll want some kind of documentation artifact.

Given a large enough piece of work - let’s say something like a total redesign of an app’s UI - there’s often a large planning document (a Product Requirements Document, or for technical plan/Request for Change, etc). See also LeadDev on RFCs

Like an epic, a planning document should be informed about the world around it. what technology, customer, or infrastructure constraints does the organization have? For example, upgrading an app to use all iOS 15 features is great, but if 75% of your customer base still use iOS 13, then you are informed by that condition.

Ideally a plan at this level should provide some concessions to scale, if you have scale. Redesigning an entire app is awesome - do you have some prebaked CSS for developers to Just Use? The more you can reduce toil at the plan level - or again, attempt to get to that stable growth plane, the better. However, sometime because of scope, technology sprawl or complex domain knowledge.

Jira has a new(?) feature named story maps. At the multi-epic level I’m unsure if this really helps, or if it’s just a way to get lost in the trees (not seeing the forrest).

Now we have:

While some agile models emphasize local control over full stack product segments, given a large enough end user application you will have unifying themes. Think corporate redesigns, deprecation of outdated language versions or other technology, or cleaning up or consolidating technical debt herd wide.

But it requires more than one planning document…

Here is where the roads start to diverge a bit, and you may need to know your audience.

From a technology standpoint some things need to happen before other things. Imagine a large cloud migration: you need to get cloud instances running in the cloud before you run stuff on them.

At a technical level, at this level, there’s likely multiple epics, and probably even multiple RFC/PRDs involved, one for each step in the process!

Now, if you have a background in Project Management, you may be thinking precedent diagrams.

Sometimes, technically, things just have to happen before other things. Here’s an example, but simplistic, precedence diagram. Read it from left -> right, things that an be completed at the same time are in the same column / Y axis.

Here we see there’s an RFC or something about booting up the VMs. Inside that plan are two epics: one about databases and one about DNS. Technically these don’t depend on each other, so could be done simultaneously.

But sometimes it is about people. Maybe there’s only one person right now that can do that work. Turns out you have a project management resourcing problem.

Likewise, for larger projects a technical precedence diagram like the one above may be too busy and may not reflect resourcing reality. Business leadership may want to see a precedence diagram like this:

If we know the approximate total story points for this work (knowing at this level the story point number is certainly likely to go up as more work is discovered), theoretically with velocity telling you how long it’s going to take.

Conclusion

This is all only useful in making large changes to a large microservice herd, and with multiple small teams doing normally independent but sometimes related work. In moving to a cloud: you have multiple teams playing a part in getting their services up to cloud standards, deploying them etc. Or take a simplistic implementation of the app redesign: each team takes the overall colors, design and UX and applies it to their own components.

In a situation where multiple planning documents are involved in an effort I believe that you need a landing “page” listing all of them. (Remembering of course that sometimes, a picture is worth a thousand words.) From one single page you can get to the planning documents, which lets you drill down to the epics, which gets you to where the technical work is getting done.

Ideally each individual technical document should give you insight into constraints of the system: business, current technology state of the project, how things were architected at a micro and macro level. In general, accessing the institutional knowledge around the transition.

But that’s thoughts for another day.