Here is my latest post for Simple Programmer…
As programmers, we have a lot on our plates. Understanding the newest technology, the business, navigating politics in the business and in our teams, and all of the tools, languages, and everything else that comes with the territory. It is overwhelming.
When it comes to making improvements, it’s easy to be in favor of our own personal development over that of our teams. Choosing to focus on gaining personal skills over improving the output of the team or the business. After all, these improvements are a manager’s responsibility, right? Possibly. But this type of thinking can backfire on us if we’re not careful.
Why? Because, ultimately, we get paid for the value we deliver to our business. So if we want more pay, more recognition, and ultimately a better career, it makes sense to keep an eye on what the business wants and needs, not just our own personal development. That’s how our checks are paid and how we keep a roof over our head.
This type of thinking can seem somewhat counterintuitive, and maybe even scary, as we’re focusing on areas that feel outside of our control.
How do we tackle our unsettled feelings?
By focusing on building skills that have a big impact on our teams. When we build the right skills on our team, we take control of the process.
One of the ways that most teams can be improved is by helping them to write better tickets. And yes, you did read that correctly. I can almost hear the united groans of programmers across the world from here. Nothing is more often the bane of our existence than something that gets in the way or programming, I know.
But — writing tickets is an art worth mastering, for your own sanity and that of your team. In this article, we’ll talk about some of the problems that teams face with software tickets and common pitfalls. After this, we’ll go through four different sections that you can add to your software ticket checklist to make them really world class.
Let’s get to it.
The Danger Lies in Our Unconscious Incompetence
Most programmers scoff at the idea that better tickets are what they need. After all, writing tickets seems to be perceived as such a simple task. Programmers working in an agile environment often have a negative polarity for documentation — citing the many waterfall projects that have failed by focusing too hard on documentation and not on doing the work. But, as is usually the case: the truth lies squarely in the middle.
History has shown me through working with many different businesses—big, small, start-up, or government—a fundamental truth:
Most companies are woefully under-equipped to write good tickets.
But this fact isn’t our fault. Many of the teams I work with are passionate, smart, and want the best for their product and their business. But if we’re working with passionate and smart people, how can we be getting it so wrong? Well, let’s take a look…
As Seneca said in “Letters from a Stoic”, “Without a ruler to do it against you won’t make the crooked straight.” The answer to how these teams end up behaving this way is: unconscious incompetence.
We can never know how good or bad our work is without a target to aim for or a benchmark to hit. So that’s what we’re going to do today; we’re going to take a look at a template — a benchmark to hit.
The Problem With Our Tickets
Before we take a look at our ticket template, we should look at some of the common pitfalls we face when writing tickets.
1) They’re Written for One Audience, Not the Whole Team — Tickets are a unique beast as they’re a document for the business but also a tool for development. Historically, these two parties speak two different languages. I mean — literally two different languages. Which inevitably leads to communication breakdowns. Often tickets are written for either the development team or for the business. Not both — which they should be.
2) There’s a Lack of Consistency — Consistent patterns help with information retrieval. Think about how hard it is to find your favorite items when the supermarket decides they want to reorganize the floor plan. Suddenly, you find yourself doing laps of the aisles looking high and low for that box of Cap’n Crunch. Eventually though, you do get into a groove and finding things slowly gets easier. We have the same problem with software tickets; they need to be consistent so we can find what we need faster.
3) There’s a Lack of information — Spending a lot of time refining tickets can feel like a waste of time. Sitting down for several hours shaping, sculpting, and improving our software tickets seems to pale in productivity over the pragmatic approach of just fucking do it (or JFDI for short). But the problem with the JFDI approach is that we help ourselves in the short-term but shoot ourselves in the feet long-term. We need to tame our tendency to want to jump ahead and take the time to do our due diligence.
As you can see, all of the above issues can be solved if we use a consistent approach: A template.
By now, hopefully you’re excited to see whether your own tickets are up to scratch. We’ll discuss the four parts of a well-defined ticket and the nuances that go into each. Let’s get to it.
Part 1: The User Story
AS AN admin user I WANT to do blah SO THAT something.
User stories help us communicate ideas that both the business and the development teams understand.
The point of a user story is to focus on business value. All technical tasks should live somewhere else — in sub-tasks or checklists, but not in the user story ticket. User story tickets are about value to the user, not technical implementation.
A user story often creates the direction of a good ticket. But it’s a deceptively simple tool.
Nuance 1 — Putting the User Back Into User Stories.
One of the nuances of a good user story is (somewhat unsurprisingly) the user part. This is the first section where you write “AS A [user] I WANT”… In our haste, it’s easy to skip over this step and quite literally put “AS A user”. I mean, they are a user after all, right?
The problem with this approach is that the first part of a user story is to link with our personas.
At this point you might be thinking: Wo-ah! Wait up a moment — what’s a persona, we haven’t talked about that? You’re right — we haven’t. So let’s do that quickly now.
A persona is a common user-centric approach for building empathy with your users by defining very specific individuals that might use your product. To bring them to life, you give them names, talk about their likes, dislikes, turn-ons, and turn-offs. By using personas, we can start to see our users as real people, not just metrics or statistics on our Google Analytics accounts.
That’s why it’s important to not whimsically skip over the first step of the user story and to take the time to define some user personas and then use them in our user story tickets.
Nuance 2 — Stories That Are Small Enough.
It’s easy to define stories that are too big to fit in our agile workflow. Because user stories can be quite high level and abstract, it’s easy to forget about all the technical work that goes into building our user story. Our stories can quickly add up to more than the time that we’ve allotted for delivering our next release. For agile teams, this time box is called a Sprint and is usually only two to four weeks.
So to avoid bloated stories, we want to ensure that our ticket fits nicely in a single sprint by breaking the feature down into the smallest reasonable parts.
It helps to think of breaking down a story like building a vehicle. Instead of building a chassis, an axle, and then finally a car, we should build a skateboard, a scooter, and then finally, a car.
Nuance 3 — Stories That Don’t Deliver Genuine Value
If our stories are too big, it’s easy to start thinking about how to deliver stories in what is known as a horizontal slice.
A horizontally sliced user story is one where we build our functionality one horizontal piece at a time. A horizontal approach might be to work like this:
The first sprint might be database features, the second sprint our API features, and the third and final sprint is our interface.
The problem here is that the story only delivers value on the last sprint. What, then, is the solution? To slice vertically.
Slicing vertically means that we do a little of the database work, a little of the API work, a little of the front-end work, and ultimately deliver a whole feature in a sprint. If you have a hard time imagining what a vertical slice looks like in practice, think of a cake. A nice slice of cake has icing, sponge, and jam all together. Not just a whole slab of icing, jam, or sponge!
Part 2: Business Context
User stories don’t just appear out of thin air; they have context, an origin, and an intention.
Consider this example:
Adding a history section to the candidate profile will allow the individual to see what actions have been taken on their account.
This feature originated from user feedback undertaken by Jenny — the findings of which can be found in documentation [here] and [here].
Delivering this feature aligns with our quarterly business goal KPI, which is: to increase candidate sign-ups.
Good leaders are able to clearly articulate a vision so that their followers can work with them to achieve it.
When we create a ticket without understanding the business context, it’s easy to get lost and deliver features that don’t really make sense to our users or deliver value to the business.
Giving business context is like using punctuation in a sentence. Without it, our communication can be unclear and misunderstood. It’s the difference between let’s eat grandma! And let’s eat, grandma!
Nuance 1 — Start With Why.
“People don’t buy what you do, they buy why you do it” is the phrase repeated over and over by Simon Sinek in his extremely popular TED talk “How Great Leaders Inspire Action.
It helps to talk about where the feature originated so that the development team understands the drivers for the change. Communicating the vision helps the development team to get on board with the feature and get excited about the value it’s delivering.
Nuance 2 — Link the Feature With Its Origins
Every delivered feature should reflect a change in user behavior.
We justify our work with phrases such as: Because Alice, the CEO wants it. But when we build products this way, we end up with a Frankenstein monster which has been built for stakeholders and not users.
To ensure we build for our users, we can link the origin of our work with the research we’ve done into our users. Or at least state the assumptions that we’re making, such as: We’re assuming that by delivering X feature, we will modify user behavior in Y way.
Nuance 3 — Be Data-Driven
Many aspects of software are guesswork. We need to objectify our work as best we can with data. Use this part of the ticket to talk about the metrics that are going to test whether this feature has in fact achieved the behavior change you wanted.
If the feature we’re building is going to drive revenue or increase user sign-ups, we want to state this fact to create a clear causal link between business value and the features delivered.
Part 3: Acceptance Criteria
Something I hear a lot is, “What’s the acceptance criteria?” But the idea of acceptance criteria means and looks different to each person. It can, however, look like…
GIVEN I am not an admin user.
WHEN Navigate to the page /admin.
THEN I see a warning box stating: “You do not have access to this page.”
Acceptance criteria is what allows a programmer to say that work is truly done. It’s a checklist. When all the behaviors defined are achieved, then the ticket can be marked as done.
Without this type of acceptance criteria, we risk having a ticket bounce between done and open time and time again. Not only is the to and fro demoralizing and frustrating for all involved, but it’s also a tragic form of waste. Instead of fixing and building nice new features, we’re busy tinkering with the same ones, unclear on when the ticket is actually done.
Acceptance criteria can be written in a format such as: GIVEN, WHEN, THEN.
Nuance 1 — Not Enough Input in Defining Acceptance Criteria
A pitfall of acceptance criteria is that it’s written without the whole team.
In order to get the most out of your acceptance criteria, assemble all those involved in working on the project and create a good checklist. You’ll want to consider performance, architecture, design, and much more.
Remember, the time invested now will pay off hugely in the long run. You’ll have coherent and easy-to-follow steps that will ensure the development team completes its work in a smooth and consistent manner.
Nuance 2 — Linking Acceptance Criteria to Your Sign Off
When you’ve got acceptance criteria, you can also use it in your automated test framework. Which means that when a ticket is complete, you can say: I’ve manually tested all ten of the scenarios defined, and they all pass. Three of them are now automated and are part of our build pipeline.
https://gist.github.com/loujaybee/cb031710f11067efb1526bd4c0c1c2b1
Part 4: Wireframes
Last but not least, the most common area of tickets is the wireframes or mock-ups.
The acceptance criteria help to define the behavior, but not the visual look and feel. We know there should be an error box, but we don’t know how it should look. That’s why we want to attach a wireframe of what the feature will look like.
Pulling It All Together
Phew — that might have been a lot to take in. There are lots of parts that go into creating a great software ticket. But hopefully, these ideas should give you a great start.
What does the ticket now look like in its entirety? Something like…
User Story
AS AN admin user I WANT to view history SO THAT I can see what actions have been taken on my account.
Business Context
Adding a history section to the candidate profile will allow the individual to see what actions have been taken on their account.
This feature originated from user feedback undertaken by Jenny — the findings of which can be found in documentation [here] and [here].
Delivering this feature aligns with our quarterly business goal KPI which is: to increase candidate sign-ups.
Acceptance Criteria
GIVEN I am not an admin user.
WHEN Navigate to the page /admin.
THEN I see a warning box stating: “You do not have access to this page.”
That’s it.
Armed with this information, you should be able to push your team and your business to a new level — which should help you and your team build faster, waste less, and save your sanity by writing really world-class tickets.
- 2023 Summary: Data Driven Stories About The Cloud - December 31, 2023
- 2022 Summary: The Open Up The Cloud System - January 1, 2023
- Open Up The Cloud Newsletter #30 (January Recap 2022) - March 1, 2022