The $64,000 Question – You want it to do what??
The Secret Sauce to Agile Development Part 3
30 years of experience getting it right distilled into my new blog!
Hello and welcome to blog number 3 in this incredible series of 12 epistles on Agile Software Development. Do your sprints feel more like crawls and your requirements change more frequently than your underpants? Then read on, as this is for you. Missed the other blogs, no bother, catch up right here:
Today, we’ll be delving into what I believe is the second most important question when building software, “How on earth is it going to work???” And once again, it’s a question that very few people can actually be bothered to ask.
Enter Phil’s Caffeine Powered Code Factory
Just BTW, I got some hardened coders to review these blogs first before dumping them up there into the cloud. These folk are red-eyed keyboard junkies who are practically glued to their machines. One of these monsters, Phil, recently invested about three grand in one of those industrial coffee machines like what they have in the Premier Inn. All you need to do is double-click the espresso button for it to automatically grind the beans and intravenously feed the coffee into your bloodstream.
As a result, Phil’s not needed to leave the desk in about six months, especially as every so often his mum pops in to top up his bean supply and hose him down with deodorant.
Let’s just say that Phil wasn’t too impressed with the blogs so far. “Hey dude, I practically had the code written myself in the time it took me to read your stupid blog.” When I pointed out that Phil’s code was riddled with bugs, didn’t do what the customer wanted, and would need to be deleted and rewritten, he responded by printing my blog out and eating it.
Connected directly to the Source, Phil’s veins run with pure Java!
That’s why we need to go beyond the user stories, features and epics that we looked at before. These are all vitally important for us to understand the business value that the software will have to deliver, but they do not contain a description of How The Software Is Going To Work.
Most likely, the main stakeholder will have a good idea of how he expects it to work or, if not, there will be a sales manager or a development lead who will want to give input. In some cases, they will want you to go away and come up with a proposal. Regardless of the source, our job is going to be to write this stuff down and to present it back, to show our understanding of the requirement and to get agreement before we start the Expensive Business Of Writing Software.
Oh yes Phil, you didn’t know that did you? You might think that typing out a bit of code or even a nice prompt on Chat GPT doesn’t take very long, well producing quality software takes a lot longer when you start thinking about say the functional, performance and security testing that you might have to do, or the price of AWS or Azure infrastructure for your test environments or maybe you need to get a crowd together to test the changes to a mobile app? We must make sure that before launching into a project that could potentially cost the stakeholder a lot of dough, that they’re happy with what we are going to do.
While it might be cheap knocking out a few lines of code, delivering working software to the client is a costly business by the time we’ve accounted for testing, infrastructure spend, staff wages, and Phil’s cake allowance.
This second type of requirement, The How, is also called the Use Case and it will be attached to the User Story.
Best thing to do here is for me to stop waffling and to dive straight away into an actual example:
🌍REAL WORLD EXAMPLE
Our stakeholder, Mr Charlie Bluster, has a good idea of how he wants his software to work and natters on at length. Our job is to write down what he says in clear language that’s easy to understand. We should also be prepared to ask questions to clarify. The stakeholder might not have all the answers, and it will be our job to help fill those out.
Empowered by a hot chocolate with enough marshmallows to build an igloo, our client, Charlie, drones on about exactly how he envisions the software to work. Here’s a small excerpt:
When someone goes to my online shop there will be a section for all the regular purchases and a separate section where we just have stuff they can buy with coins.
The idea is that they scan the QR code at the back of a book to go to the review page on our website. Once they’ve logged in, they’ll get the chance to type in what they think about it and maybe assign a rating to it. We have to be careful here and not allow and bad language or other stuff into the review text, that stuff gets knocked out straight away, (to be fair, I don’t mind bad reviews as it can help improve the products). If the review hasn’t any profanities it gets posted up to the appropriate page on the website, so for example if they review my book the Un-god of Fate, then when you go to the Un-god of Fate webpage, you’ll see all the reviews there with the best ones listed first.
Of course, you could do this by pressing some sort of big red ‘leave review’ button on the website or if its not a book, say it’s a digital product, then you could just click a link.
Once they’ve left their feedback, they’ll get a nice email thanking them and it will tell them the number of coins that have been added to their account. When they go onto my online shop, aside from all the normal products, there will be a list of stuff they can buy with just coins. This is mainly going to digital products like eBooks, PDFs or stuff like that.
Time for us to stick in a timely question: Why, Mr. Bluster, did you mention Pokémon?
Right now we’re just talking about the website but I also want to bring the shop into my games. I’ve got a few mobile games available already, (these are written in C# btw), and I want to have research tasks, just like in Pokémon Go. Once you complete the research task then it comes up with a nice message, and awards you some coins. There’ll be a big list of all the tasks that you’ve completed and the ones that are outstanding. You’ll be able to go directly from the list of tasks, or indeed the game home screen to the shop to spend your coins.
Of course, any code that we write has to be reusable across all the games.
Phew, this guy could waffle for Britain, keep smiling Phil and pretend to be nice.
Our job now is to write these requirements down in a way that will facilitate the development of the software and that will also show our understanding of what is being asked. We will replay these use cases back to the stakeholders later and, in fact, give him a copy to be perused at his leisure. This will also make it easier for him to send back any comments or updates.
Despite spewing out more text than a Xerox on steroids, we must capture what our stakeholder wants, assuming, of course, we want to get paid.
🍟TAKEAWAY TODAY, USE THE SOURCE LUKE
Take your time and get this right. We learn from Master Yoda that a Jedi’s strength flows from the Force, in the same way, good quality software flows from good requirements, get this bit right and the rest of the software will be easy. Get it wrong and you’ll be in a worse mess than when Darth Vader had to explain to his boss what happened to the Death Star.
After losing his favourite toy, Darth is forced to take alternative transport to work.
But how on earth do we take the customer’s babble and turn it into proper requirements? Don’t be tempted just to take the text and save it in Jira or somewhere else and refer back to it now and again. Do this and the developers will end up coming up with their own method to solve the problem and the resultant software will be different to what the customer is looking for, (looking at you Phil).
Don’t worry, punters, we’ve got the answer right here:
First of all, let’s split the text up into the different use cases. For now, we’ll focus on the part where the user is going to submit a review to avoid this article getting out of hand.
First, here’s the text again:
The idea is that they scan the QR code at the back of a book to go to the review page on our website. Once they’ve logged in, they’ll get the chance to type in what they think about it and maybe assign a rating to it. We have to be careful here and not allow and bad language or other stuff into the review text, that stuff gets knocked out straight away, (to be fair, I don’t mind bad reviews as it can help improve the products). If the review hasn’t any profanities it gets posted up to the appropriate page on the website, so for example if they review my book the Un-god of Fate, then when you go to the Un-god of Fate webpage, you’ll see all the reviews there with the best ones listed first.
Of course, you could do this by pressing some sort of big red ‘leave review’ button on the website or if its not a book, say it’s a digital product, then you could just click a link.
Once they’ve left the feedback, they’ll get a nice email thanking them and it will tell them the number of coins that have been added to their account. When they go onto my online shop, aside from all the normal products, there will be a list of stuff they can buy with just coins. This is mainly going to be digital products like eBooks or PDFs or stuff like that.
There’s a lot of spurious language in here, ‘ifs and maybes’ and so on, let’s cut all that out and reduce the amount of text that we have to work with:
They scan the QR code at the back of a book to go to the review page on our website. Once they’ve logged in, they type in what they think and assign a rating. We’ll remove bad language from the review text, (bad reviews are ok as they can help improve the products). If the review hasn’t any profanities, it gets posted up to the appropriate page on the website, organized by the best reviews first.
Alternatively, they can press a big red ‘leave review’ button on the website or click a link.
Once they’ve left their feedback, they’ll get an email thanking them with the number of coins added to their account. When they go onto my online shop, aside from all the normal products, there will be a list of digital products like eBooks or PDFs they can buy with just coins.
We’ve just dropped the amount of text by half, a good start. The next problem with the text is that we really don’t know who is carrying out the actions. It’s a good idea at this stage to specify the names for any ‘actors’ or users of the software. In this case, the actions are being carried out by an end customer who already has an account on the website, let’s call them an ‘authenticated customer’.
We also want to look out for words in the text where multiple terms have been used to mean the same thing. For example, Charlie refers in one place to ‘the review’ and somewhere else to ‘the feedback’. Are these two completely different things, because if they are they will turn into two separate entities in the code later on. At this point, we want to clarify and if they are the same thing, settle on the right word that can be used for both and eliminate the duplicates. If we take these things together, we now have something like the following:
The authenticated customers scans the QR code at the back of a book to go to the review page on our website. The customer types in what they think and assigns a rating. We’ll remove bad language from the text, (bad reviews are ok as they can help improve the products). If the review hasn’t any profanities it gets posted up to the appropriate page on the website organized by the best reviews first.
Alternatively, the customer can press a ‘leave review’ button on the website or click a link.
Once the customer has left their review, they’ll get an email thanking them with the number of coins added to their account. When the customer goes onto my online shop, aside from all the normal products, there will be a list of digital products like eBooks or PDFs they can buy with just coins.
🧻INANE RAMBLING, in the Green
Another thing to look out for in the use case text is any description of the user interface. For example, Mr. Bluster has mentioned that he wants a big red ‘leave review’ button.
I remember a similar project where the use case description clearly stated that the button would be displayed in Green to highlight it and then when pressed the data would be exported to a file and saved to the C drive. Sounds ok? Yeah, well I don’t see why not, I mean if that’s what the customer wants then that’s what he’s going to get.
No problem at all if we’re working with his old Amstrad CPC 6128 when all the screens were green. Ah, what a machine that was, way ahead of its time, the keyboard clicked like a cricket and the disk drive purred like a happy kitten, (sigh).
A true work of art, the CPC brought disco to our homes.
Anyway I digress, the requirement went through to the development team, who all had a good laugh. Why? Well, because the software was for a health and safety mobile console used on big construction plants. It only had a black and white screen, and guess what, no C drive.
Doh!
The normal rule here is specify how you want it to work and leave the solution to the development team. Yes of course, there will be cases where very specific UIs or Look n Feels that have to be implemented, but what we’re doing here is specifying how the logic of the software is actually going to operate. If there’s a screenshot or a set of styles that should be adhered to, then attach them to the use case and make sure that information is recorded.
Anyway, back to refining our requirement text. As we’re trying to get down to a logical description of how the software works, a good rule is to deal in actions and system responses. For example:
The user presses a button and the system provides a response.
Similarly organizing our text will make it easier to write the software later, and it will also help structure the text better:
An authenticated customer selects a book, a game or any other product to review. Alternatively, they could scan a QR code or click a review link or button on a product web page. The customer enters the review, including a rating and text. The system checks the text for profanities and, if clean, approves the review. It awards coins to the customer and sends them an email with their balance. The system displays the review and the name of the customer alongside the product, listing the highest ratings first.
Ok, so what we’ve got here is a much tighter, better-defined piece of text that’s easy to read. We can replay it back to the customer and get their agreement and we can easily pass this onto anyone in the development team, regardless of what their role and skills are, and they should be able to understand how the software is going to work.
If there are extra things that we need to keep note of, we can record these as additional technical requirements.
For example, through further conversation and background research, we discover that the customer's existing website has been built using a tool. Therefore, we can record:
- The code must work alongside the customer’s existing website, which has been built using the MailerLite Low Code tool.
- The look and feel should match the existing website.
Charlie’s shop over on his website, www.CharlieBluster.com. Simple and clean looking, it should be easy to fit our code in there. (Charlie: and you can buy loads of cool Blusterverse merch, head over there and get your pressizes now!)
🌶️HOT TIP
Always link your use case to the user story and include any technical constraints. If it’s not in the system, it’s not in the sprint!
Here is the full requirement including the user story, the use case and the additional notes within my ADO instance. I’ve just pasted them directly into the description underneath the story text for now.
ADO allows me to store the use case text directly inside the story description.
🤖How can AI make this stuff better?
Writing the use case is one of the most important parts of the overall software development process. Yes, sure, you could dump all the customer’s babble into CoPilot and ask it to come up with something, but then you’ll lose control over the process.
Far better to write it yourself, alongside the customer, if at all possible, and maintain that deep understanding of what must be delivered. (Don’t forget that Customer Collaboration over Contract Negotiation is one of the key tenets of the Agile Manifesto).
That being said, the AI can certainly be useful for reviewing your text and suggesting improvements; however, my recommendation is to do the majority of this work by hand, and to be honest, it’s not going to take very long.
So, what do you think about that Phil, hmmm? I’m pretty sure you had a solution in your mind after the last article, but is it what the customer is actually looking for? Because, if it isn’t, you would have to start all over again, (Phil, grumble, grumble, stupid customers, grumble moan).
TUNE IN NEXT TIME
Before we pile in, start writing some code, and spending all the customer’s hard-earned dosh), it’s a good idea to figure out if we can actually implement what it is he is looking for. That’s why in the next incredible instalment of this stellar blog, we’re going to explore Solutioning.
I’m afraid that’s it for blog 3, Sayonara dudes and don’t forget to tune in again in 2 weeks' time. In the meantime, you can download the main notes from this article right here, which today also includes my coveted No-Nonsense Guide To Writing Use Cases—complete with real-world examples, industry horror stories (that I’ve seen a thousand times over), and the kind of advice you won’t find in a text book, (Phil: oh mummy that’s just what I need).
Now go practice writing requirements and don’t forget that if you leave gaps in the spec, Phil will fill them with his own crud code!
Please share our blog page on your socials:
🧃Juicy Download
MUAHAHAHA, I’m not going to give you all my secrets at once, if you’d like my No-Nonsense Guide then it's available in today’s Juicy Download, where I’ll also be expanding on my rules to reduce the use case text. This cornerstone of development documentation is available at the miniscule cost of only £1, which is needed to fuel my own cake addiction.
Additional Image Credits
- Image of the Amstrad CPC is by Morn and shared under the CC-BY-SA 3.0 license.