Foundations of Ticket Writing

For web development test engineers, one of the most common tasks is lowly defect ticket creation.  Each ticket is a valuable nugget of feedback provided to the development team, but the caveat is that it is provided at the end of a project. Nerves become frazzled while timelines get tighter.

Key Ticket Concepts

A vital requirement for each ticket is that it is clear, concise, and distilled as much as possible. I try my best to use an editing eye with my ticket, knowing that the developer may look at hundreds of tickets. I highly recommend using a tool like Hemingway for a few tickets, which dissects the text readability levels. When I write a ticket, I try to keep the non-technical language at an 8th grade reading level – this distills the information to the developer diagnosing the issue.

While working on each ticket, I do my best to give feedback in a neutral manner. It may seem obvious to not include negative commentary in each ticket, but I also try my best to not include positive commentary (smiley faces and similar). Both can cause strife and imbalance on the development team – a developer dealing with a difficult ticket may feel slighted when another developer receives a positive comment. Using neutral language helps a developer simply diagnose an issue without emotion.

Additionally, being careful of language that presumes is one lesson I learned as well. It was pointed out to me that the small word “should” added to a behavior expectation I never thought would irk a developer. For example, “Expected Behavior: The site should include a favicon.” adds presumption with the word ‘should’. It never occurred to me, this simple word, would rankle a developer. Instead, it’s better to simply provide straightforward language: “Expected Behavior: the style guide shows a favicon is added to the site.”. It also references a precise location in the documentation that defines a defect.

Constructing a Ticket

One thing that I believe helps the developer quickly diagnose a defect is a very clear title: “Global – Favicon Missing from Site”. The location ‘Global’ helps define its greater location (or, for example, “Careers”). For the title of the headline itself, I try use MLA Style headline casing, and try my best to keep it as short as possible. I’m dorkily pleased if I can get it under 60 characters. If the defect only occurs in one environment, I display an abbreviated version before the location: “[IE7] Global – Favicon Missing from Site”. More information is provided in the ticket of the specific detail, but the abbreviated environment also helps the developer eliminate possible issues.

Within the body of the ticket, I provide an Issue Description, an Expected Behavior description, affected URL(s), an Environment reference, and a screenshot or short video. If the defect is triggered by a process more than two steps (generally a UI issue not related to CSS), I will also provide Steps to Reproduce.

The Issue Description is a short sentence or two describing an issue, and its converse, the Expected Behavior, notates what is defined as being necessary to the project. These seem obvious, but it is imperative to be clear for the developer’s sake. If a developer sends back the ticket for clarification, they have taken the time to open it, read it, attempt to understand it, potentially switch their train of thought, but then send it back for clarification. This means the developer has wasted time simply comprehending the problem – which I will have to clarify anyway. For me, my personal acceptable rate of clarification is 1-3% of tickets written may need further information.

Environment references are essential for the developer. Providing a simple ‘Google Chrome’ isn’t enough – I also am sure to provide the operating system, as well as the version number. For example, today I’m using the Chrome version “Mac OSX 10.8.5, Chrome 35.0.1916.114”. It’s essential for the developer (and is one of the first reasons the developer requests information from the tester), but there are many times defects that only occur in specific environments.

The screenshot (or video, if appropriate) gives a developer a visual cue of the defect. There are many tools that can gather screenshots, but I use the simplest method of Command+Shift+4 on my Mac computer. Research methods that work best, and the developer will be appreciative and will be able to comprehend the ticket even faster.

I personally do not include Steps to Reproduce if it is a simple CSS issue, or one that can be quickly understood when landing on the page – if there is a button that has an incorrect color, or if a login form is not present on the page. Otherwise, the Steps to Reproduce are the final chance for the developer to understand the problem. I try to make them detailed and almost nauseatingly step-by-step, so that nothing is missed.

But You Test, And You Might Know Some/Most/All of This Topic

Well, I’m really pleased. This makes development easier for everyone, and you’re able to give iterative feedback in a more constructive manner. Perhaps you’ve taken this template and tweak it to your own for your group’s projects – this is definitely the just the basics of a ticket.

When I first started with testing, I learned a bit of this from a fantastic tester, and the rest was picked up along the way. I’m hoping this goes out to someone just starting out, or making the leap to Quality Assurance from another career path. I also find it helpful for trusted folks who aren’t testers that contribute to a project provide feedback to the development team. I think that providing clear feedback throughout any project will amplify your project’s quality, and the basics gets your team started on the right track.

About the Author

Sara Tabor is a NYC-based Director of Quality Assurance for Noise, a marketing and analytics agency focused on the millennial market. She has been testing for 6+ years, having prior worked in quality assurance at The Nerdery and Magenic. Her focus is manual testing, with additional background in auditing, accessibility testing, and localization testing, and works to foster quality assurance standards throughout the agency development experience. When not breaking code, she can be found playing hockey, waterskiing, knitting, or unhooking her cat’s claws from her clothing.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.