Hey developers! If you get a ticket with very little detail it's a good time to practice adding some. Being able to add detail to a ticket is a step you can take toward career advancement. There are three types of details you can start using right away; Acceptance Criteria, Steps to Completion, and Resources. As an example, I'll be showing a real-world ticket from my side project, Contests by Brooklet.
Acceptance Criteria#
First, write some "Acceptance Criteria". This is the checklist you should go through to determine whether or not the ticket is complete. Answer the question "How will I know this is complete?" This often takes the form "When the user does X, then Y should happen". Don't forget about the edge cases!
Example:
You get a ticket like "Add 'Accept Invitation' Flow" with very little detail. All it says is, "Users accepting invitations should be asked to register, then be able to accept or deny an invitation". As you start to think about it you realize it could use more detail. So you write some acceptance criteria:
When a user opens the app and taps "Accept Invitation"
They get taken to the "Register" page
The message "Register with the invited email address" is shown
After registering
The user is taken to the Home screen with the invitation dialog open
The user's invitations should be displayed
When the user taps "Accept" in the invitation dialog
The invitation should be removed
If a contest of the correct type (from the "contests" list) does not exist
one should be created.
The user should see their contest
and contests that have been shared with them.
When the user taps "Decline" in the invitation dialog
The invitation should be removed
Writing a step-by-step description of user flows removes guess-work. Share your improved acceptance criteria with your boss or teammates to solicit feedback. Talking about detailed user flows ahead of coding will prevent you from heading down the wrong path.
There's one thing missing here and that is handling error states.
If invitations don't load
Show a retry button
If "Accept" or "Decline" requests fail
Show "Snack Bar" popup indicating the user should try again
Take some time to identify error states and you will prevent future bugs from showing up later on.
Steps to Completion#
Next, write the steps you'll take to complete the ticket. Something like "Create a model. Create a component. Request data from the server. Populate component with server data." These are the engineering tasks you have to complete in order to achieve the user flows described above.
Example:
Create a registration screen for accepting invitations
Create the invitation dialog
Fetch invitations, store them, and show them in the dialog
Handle Accept and Decline user actions
Create a contest when accepting if no contest of that type exists
Show shared contests on the home page
These notes are for you more than anyone else. Planning out the components involved in a user flow is a basic form of software architecture. Considering how the pieces of software go together ahead of time will help you create code that's easier to read and comprehend.
Resources#
Finally, collect any resources you'll need. API references, data structures, or open questions may all appear in this section.
API Endpoints to use
- GET /invites
- PUT /invites/{id}
- POST /contests
Data structure for the invite application state
{
[invite.id]: invite
}
Does the contest automatically get created by the API when accepting an invite?
This is another reference for you. Put important information in the ticket so that you can quickly find it later on. Listing endpoints and resources can also help you identify missing things that need to be completed in other tickets or by other teams.
Reviewing Your Work#
At this point, your ticket will look like this with all the detail you could need.
Acceptance Criteria:
...
Steps:
...
Resources:
...
Often times when you add detail to tickets you'll notice that there is too much for one ticket to encompass. It's useful to identify bloated tickets before starting development so that you can break up work and manage expectations.
Continuing to Grow#
As with so many things, adding detail to tickets is a skill that you can practice and improve on over time. As you get better, you will likely be asked to break down larger and larger pieces of work. Next thing you know, you'll be writing stories for the rest of your team to complete. You'll be performing the lead developer role!
Feel free to send me your questions and thoughts on Twitter @jimboolean!
About the Author#
Jim Hall is a software engineer and engineering manager at Dynamo Metrics. In his free time Jim enjoys coding, telescoping, and cooking.
This article is based on a series of tweets I wrote in July 2020.