How to write a great product development ticket: 10 must-have sections to follow
Throughout my career, I have probably written hundreds (or actually even thousands?) of development tickets. Even though every ticket’s journey is different, I have established a unified structure, which acts as a facilitator in the development refinement process.
Far too often I see product managers think of their tickets as an end result — something they will write on their own in one or two sittings — and ONLY after they are clear about their requirements. I beg to differ.
I have built my template to guide me through the process — activating different perspectives of my own thinking so that I could clear out blockages early on and create a well-rounded development in the end.
I start with an empty template as a backbone of my ticket. With every discussion, I’ll go back and add more meat to the bones. I use the ticket actively and on a daily basis until I have cleared out all uncertainties. As I grow clearer about what I want to achieve, the development ticket will grow with me.
Here is my template:
- Motivation and Business Impact
- User Story Statement
- User Interaction / Design / User Flow
- Functional Requirements and Developer Notes
- QA Notes
- Not in Scope, Questions and Answers
- Links and References
- Affected Ventures
- Affected Platforms
- CC and “to be informed”
1. Motivation and Business Impact
Purpose: I will state clearly the reasoning of my development’s existence and I MUST be clear about the value!
What has triggered the development? Any relevant business context, links to business cases, impact and value context. What are we trying to achieve and why is it worthwhile? How big is the impact and how will it be measured?
Usually this section is in a free-flow storytelling format, however lately, I have found a good template to be added to the mixture — borrowed from the Hypothesis Driven Development (HDD). It will force me to write out the success measure and value of my development in an even clearer manner:
- We Believe <this capability>
- Will Result <this oputcome>
- We Will Have Confidence To Proceed When <we see a measurable signal>
I wrote about it also in another article: Avoid Ambiguity with HDD
2. User Story Statement and High-Level Acceptance Criteria
Purpose: Here I will think and formulate high-level outcomes for this particular development. As an end-user, what should I or should I not be able to do after this development is completed?
I usually stick to the common 3 templates to activate my thinking. Sometimes, I try all of them and see if it triggers any new perspectives in my mind.
Classical User Story Template
- As a < type of user >, I want < some goal > so that < some reason >
Behavior-Driven-Development: BDD
- Given <pre-condition>, When <action>, Then <result, outcome>
Job Story
- When <situation> , I want to <motivation>, so I can <expected outcome>
From Jobs To Be Done: Replacing User Story with Job Story
3. User Interaction / Design / User Flow
Purpose: This section communicates clearly what the user will see, however, it also serves as a knowledge base and guide for developers (or whoever else might come across this ticket) to know how the user is currently using a particular part of the application and how it is designed to be changed. As there is always a lack of documentation about historical features, then this aims to give the context and understanding of how the functionality is changing compared to the current situation.
Template: no particular template, just step by step run-through of the user’s journey with screenshots and mockups (or references to it)
My thinking about UI development has been shaped strongly by the mentality of “Don’t Make Me Think” — from the same-named book by Steve Krug. Are my messages, buttons, and fields self-explanatory? Can my user recover themselves from an error? Am I thinking of what is prominent and secondary information on the screen — do we make adjustments to our solutions accordingly? Oh, and most importantly — have I considered and talked to my users (well, I am lucky and my users are all internal so that I can easily talk to them!)?
4. Functional Requirements and Developer Notes
Purpose: Until now, the development has been described from the business value and user perspective — now it is time to get precise and more technical — it is time to flesh out the requirements specification.
What kind of validations do we need? What type of data will an input field accept? etc. Also, Developers can add any information they have and need for the particular development — could be perfectly co-created during grooming sessions!
Template: no particular template, it really depends what is needed, but very often I turn to diagrams, schemas (like Business Process Modelling — BPM) and information presented in tables 😄. Yeah, I very much like to create tables on my tickets…
5. QA Notes
Purpose: This is such a magical part of the ticket! Up until now, I have been thinking of the happy paths — what and why I want to build, how is it gonna look like, etc. But the QA section is there to force me to switch the hats and to think like a QA. I use the “test to break” approach — What could go wrong? What could the user do that I do not intend them to do? What if my value I expect is suddenly “null” — how would we handle the situation?
Almost every time, I have discovered additional requirements to be added to the development purely by thinking like a tester who wants to break my solution!
If you have a permanent QA in your team, then here you can give guidelines to them on what kind of combinations and scenarios you want them to cover. It is also a section for the QA to write about their testing plans.
Template: it’s not really a template, but rather a way of thinking — test to beak.
6. Not in Scope, Questions, and Answers
Purpose: During discussions, we have always questions coming up — as we figure out the answers, I will document them all here. Also, if we decided to leave anything out from the scope, I will note it here.
Future Heily has thanked the old Heily so many times when she has gone back and read through the notes on why she did or did not decide to do smth.
I call it #payitforward!
7. Links, References
Purpose: Boy, have I sometimes struggled with those old development tickets I have come across. They are so empty — not enough context, not enough information, so many unanswered questions and no idea where additional information might be hiding. To be kinder towards future generations — I will add any references to the documentation I have found about earlier developments AND add notes about new documents, g-drives, confluence pages that I have created.
Your future successor or a team-mate will LOVE you for it!
#payitforward
8. Affected Ventures
Purpose: Just a reminder to mark down on which application venture this particular development is going to be enabled. Sometimes we have forgotten to mention it and needed to deal with some uncomfortable consequences.
9. Affected Platforms
Purpose: This part will reinforce me to think whether my development might actually impact anyone else in our organization and in our tech stack?
To trigger the right kind of conversations — we have established a list of our platforms and services across the ecosystem. With every development, we can ask ourselves — is it impacting or needing any other systems involvement?
10. CC or “to be informed”
Purpose: Last but not least — I would tag here PMs or area representatives (customer support, business teams, etc.) who might need to be aware of this development. These people usually might not be directly connected to the development but it would be good for them to be informed.
Summary
The template I use reinforces me to make sure I think of the following:
- Is my value and business case clear?
- Am I clear what my users need and how they will use the application? Am I making it easy for them?
- Have I thought deeper than just the “happy path”?
- Am I paying forward and helping to build a knowledge base?
- Am I making a broader audience aware of my developments?
I find this template serving me and potentially anyone who would use something similar. Yes, it may feel uncomfortable and sometimes annoying to follow. The best indicator for me is — if I am not able to flesh out any of the sections or get stuck — I have still work to do, more questions to ask! However, trust me when I say — it will make your development ticket very strong and well prepared. It would reduce the possibility of setbacks and delays coming from unthought-of cases and sudden surprises.
How does your template look like? Did you find anything new to try out yourself?
Happy Ticket Writing!
Cheers,
H.
