Requirements Served Hot, Epics, Features, Stories and PASTA!

The Secret Sauce to Agile Development Part 2

30 years of experience getting it right distilled into my new blog!

Hello and welcome to blog two of twelve in this incredible series on agile software development, that is today, branching out into food and by extension, software requirements!

Not heard of this blog? Then check out the overview to this sizzling series of sensational scripts that will surely transform how you look at coding.

So what is a user story, what is a use case, what are t-shirts to do with it and I always thought that Fibernacii was a type of pasta?

Preparing for her daily attack on the Terrahawks, Zelda gets to work on a fresh bowl of Fibernacii!

Requirements may come to you in all sorts of forms, whiteboard drawings, the musings of a CEO, or even a vast spreadsheet of highly complicated technical details.

Regardless, our job is to get those requirements into a form that will facilitate the creation of the software, including the tests, infrastructure, documentation and everything else that goes with it. These requirements will be presented in plain language for everyone to understand and they need to be stored somewhere that is easily accessible. If you’ve got ADO or Jira that’s wonderful but to be perfectly honest, you can get away with Trello, Planner, or even a good old-fashioned Word document, (as long as it’s held somewhere centrally like SharePoint).

Before you gloss over this entire blog and dump it straight into the trash (as sure there is nothing easier than requirements gathering), let me tell you that this part is Really Easy To Stuff Up. I’ve seen some atrocious examples of really poor requirements over the years that were written down by what were thought to be competent BAs or Software Developers.

Here is a fun selection of tasty treats, these are all (and I promise), actual examples from real projects.

Fun requirement 1: Change the text to make it easier for the customer
Fun requirement 2: Move the button here
Fun requirement 3: Make an accountancy system

INANE RAMBLING and Negative Nigels

Ha ha ha, what a lot of rubbish, yet people actually believe these are valid requirements!! The first one, Change the Text, turned up in the ADO system for a big government department that was building an external website for the education sector. The requirement was actually logged by a call centre operative who was getting far too many annoying customer phone calls because the poor users couldn’t understand the text on the website.

The operator, in his vast wisdom, thought that the problem could be solved by changing it and therefore reducing his call count.

Sweating it up in his call centre, poor Nigel just wanted a single code change to stave off insanity for one more day!

The requirement got picked up by the development team, who laughed it off and forgot to put it in the next sprint, Coz Sure What Idiot Would Log A Requirement Like That And It Will Only Take Three Seconds To Change A Bit Of Text Anyway.

Eventually, after many, many sprints, it got picked up off the backlog, the dev and tester agreed on some superficial change, which didn’t take long, and it got released. Of course, the ticket didn’t contain any specifics, there were no contact details for the call centre guy, and no real clue as to what the actual problem with the text was. The net result was that it made the website more confusing and poor Nigel was inundated with even more calls.

What should have happened was that our operator, or the BA that dealt with him, wrote down why the change was needed and let the dev team come up with suggestions that could be checked with the end user. There should also have been measurements of success to see if the change was working. Perhaps by attaching Google Analytics to the website and measuring the volume and subject of support calls being made?

Nah, don’t be stupid!

This silly little story begs us to ask the question:

How should we record requirements that don’t make Nigel cry?

Before we can go any further forward we need to understand the difference between two really important terms, the Use Case and the User Story.

But sure, a User Story is just a new form of Use Case, it’s an agile term, grandad, that old Use Case stuff went out with the Ark when they finally outlawed C++??? DOH!!!!

Good coding practices were wiped out by the flood at the same time they invented Javascript.

Nothing could be further from the truth. Here is what these terms mean:

A User Story describes the Value to be delivered by the requirements. It tells us Who wants the requirement, What they want, and Why they want it.
A Use Case describes How the software will work

User Stories are also grouped together as Features and Epics. Just like User Stories, Features and Epics describe the value, but they are typically bigger requirements.

Our backlog will contain the user stories with each story having one or more use cases attached to it. If we see a requirement and if there isn’t a clear answer to the four questions of Who, What, Why and How, then the requirement is incomplete and shouldn’t be on our backlog.

Today, however, we’re going to investigate User Stories and come back to the use cases later on.

Writing down the requirements – Epics, Features and User Stories

REAL WORLD EXAMPLE

Going back to our example from blog one, (you can read it right here if you missed it), our stakeholder is looking for an online shop where customers can spend coins they’ve earned buying and using his various products, a bit like the shop in Pokémon Go.

Pokémon, a gift from heaven guaranteed to keep my kids amused for 5 minutes, letting me get some blogging time in.

We should write down, who, what and why, and we need to do this in clear language without any ambiguous terms.

Let’s start by serving up our overriding requirement, called the Epic:

Who wants it? Our main stakeholder, the owner of the business.

What do they want? An online shop where customers can spend coins earned through purchases, reviews and achievements.

Why do they want it? To increase customer interaction and generate profit.

We can write that all down in a single sentence:

As a company owner, I want an online shop where our end customers can spend coins earned through purchasing, using and reviewing our products to increase our customer engagement and profits.

Now, lots of competent people can sometimes struggle with getting this sort of thing down. It can be hard to get started, so I’ve got two tips for you.

The first one is simple and that’s just get something down, even if its complete rubbish with bad grammar and spelling mistakes. Just get it down, let it sit for 5 minutes and then review it and make some corrections and improvements. After a few tries at this you should start to approach something legible. If you’re doing this in a workshop with other staff or with the customer then get it up onto the whiteboard and work on it together which is a good collaborative exercise helping everyone to feel bought it.
This is also somewhere that AI can help, paste what you’ve got into Copilot, ChatGPT or your favourite electronic friend and see what it comes up with. You can also use the AI to check what you’ve done.

Here’s what Copilot has to say about it:

Ultra-smart AIs can be used to help nail that story text.

Wow, that’s hardcore; it comes pretty close to my own version of the epic. Either I’m just as smart as the AI or possibly both of us are thick, (Nigel: yeah dude, it’s surely that second one).

Moving on! The Epic is obviously quite big and we should be able to break it down into a few separate Features. Here is an example:

As a customer, I want an online shop where I can obtain digital products for free by spending my coins.
As a customer, I want to earn coins by reviewing products so I can get other products for free.
As a customer, I want to earn coins by completing achievements so I can continue the fun.
As a customer, I want to earn coins by purchasing products.
As a company owner, I want to monitor coin usage and shop activity so I can measure the impact on customer engagement and profits.

Once again, feel free to ask the AI and see what it suggests if you’re struggling with this bit. It can really help speed things up.

That’s awesome, chief, we can start coding straight away!

Faced with a set of user stories like this, many Scrum Masters will organize a Sprint Planning Session with their development team and use sexy and cool-sounding techniques like Planning Poker to assign Story Points to them. Wow! Sitting down to Story Time and Playing Planning Poker sounds a whole lot better than actual work.

In such a session, people loaf around consuming vast quantities of energy-boosting drinks and get high on sniffing ozone from the photocopier. They bandy about the names of the very latest Javascript languages to show how modern and cool they are. Everyone slaps each other on the back, confident in the knowledge that they are more cutting-edge than SpaceX.

In professional Sprint Planning sessions, productivity is directly proportional to caffeine concentration.

Now, don’t get me wrong, assigning story points and planning the sprint are really important things to do, but it’s not the right time to be getting into that.

A lot of teams, however, do their sprint planning once the user stories are defined, then they go straight to the coding stage.

Let me ask you a question, which is a question that the person paying for the project is also going to ask you, and that is: how long is it going to take to deliver this? Are you able to answer the question, can you see in your mind’s eye everything that needs to be done and how long it is going to take? Well, if you can, then stop now because I tell you that you’ll be wrong!

What hold on! Don’t be so stupid! We can use historical analysis and cool techniques like recording the team velocity and using the Fibernaci series to predict how long it’s going to take. We’ve already got our story points in place, so I don’t see what the problem is. Move over, grandad, and get out of our way!

These sorts of people might even be tempted to tell the budget holder that in today’s modern world, we don’t deal in time estimations and that he is stupid for even asking the question about how long it will take. Agile processes we will tell him are all about delivering value, and you’ll get something to your liking pretty quick!

Don’t do this, it’s a guaranteed failure. Even if your velocity analysis is good and by some fluke you are able to get close to an estimate, then I will tell you now that what you provide to the customer is going to be wrong, you’ll have wasted your time and effort and everyone will be in a bad mood. Don’t believe me? I’ve seen it a million times before in projects all across the world.

The problem is that there is a really, really, big important question we haven’t asked the stakeholder. And the answer to this question is going to make our jobs as software developers really easy and it’s going to enable us to answer that all-important question of ‘how long is it going to take’ with a realistic degree of accuracy.

What is the question I hear you ask, well, you’ll have to wait until the next blog to find out!!

Before we finish off for today, let’s make sure that our user stories are arranged nicely, somewhere central for everyone to see. I’ve used Microsoft Azure DevOps, as it’s a great tool and free for individuals and small businesses, here they are now:

The Epic and Features in Microsoft Azure DevOps

Here’s the Epic. I’ve also included our value measurements and benchmarks from the first blog, as these are what we’re going to have to hit.

🌶️HOT TIP

Make sure that the measurement of value and the benchmarks are stored alongside the epic. It’s these measurements that are the real test of whether the software will be successful or not.

TUNE IN NEXT TIME

In the next tongue-tingling episode of this tantalizingly tasteful series, we’ll be exploring that big question I mentioned earlier that’s going to make your lives as developers much, much easier.

But before I sign off, here’s a final little treat. I asked Copilot to review my blog and it nearly exploded with joy after processing it. It did spit out this lovely little acronym, which I decided to include to round off:

🥄 PASTA Framework – The Agile Recipe for Requirements

Purpose – Why does this matter?
Actor – Who wants it?
Scenario – What’s the situation?
Target – What outcome are we aiming for?
Assessment – How will we measure success?

I’m afraid that’s it for blog 2, Sayonara dudes and don’t forget to tune in at the same time next week, and please, please share this on your socials.

Additional Image Credits

Noah's Ark Vectors by Vecteezy