QA Basics – Bug Writing Pt. 5

Welcome back to QA Basics in game development!

It’s time for the penultimate post in Bug Writing! Today we’re tackling the last few bits in one go. They’re key parts of a bug but there’s not a huge amount to go over, so I’ll just outline what they are and give some points on how to approach them.

We’re going to look at:

Then at the end, I’ll talk about some notable exceptions and why I don’t use them. Let’s dig in!

Expected Behaviour

First of all, I go with Expected Behaviour instead of Expected Result because I find it works better with game development. A “result” is great for very specific requirement but “behaviour” gives a little room for intepretation and you’ll find out why I think that’s important soon, maybe you already have an idea.

There’s two types of Expected Behaviours really, the behaviour outlined in the game development documentation and the behaviour expected by the player. If you find an issue that contravenes what the designers outlined in the G.D.D., quote that section from the G.D.D. in the Expected Behaviour. If you find an issue that doesn’t explicitally contravene the G.D.D. but just doesn’t feel right or it makes the game less fun then well done! This is your chance to influence how the game is designed. Make sure it is clear in the Description that although it’s not technically wrong, you think a change sound be made. Use the Expected Behaviours to guide the design team to improved gameplay.

Don’t see this as an opportunity to go crazy nit picking every bone you have, it’s unlikely there will be the time to address everything. But if you’ve got something that you think will really make a difference, this is where “Behaviour” is better than “Result”.

Let’s do two examples! We love a good example here!

Bad – Contravenes G.D.D.

Expected Behaviour

🔹The player shouldn’t be able to fast travel in this situation.

Good – Contravenes G.D.D.

Expected Behaviour

🔹According to the GDD “Combat States and Restrictions”, “fast travel should be disabled while the player is flagged as in combat”.

I know, I know. More words. But this is all for traceability and I don’t mind some extra words for that.

Bad – Contravenes Player’s Expectations

Expected Behaviour

🔹Jumping should make sound even if you’re sneaking.

Good – Contravenes Player’s Expectations

Expected Behaviour

🔹Enemies are alerted to “noisy” actions performed by the user in ‘Stealth Mode’.

Description

Currently, jumping while in sneak mode makes no audible sound and does not trigger enemy detection, even when landing directly next to an NPC. While the GDD does not explicitly cover the sound behaviour of jumping in stealth, this behaviour is counterintuitive. In similar RPGs (See Notes), and in other parts of this game, overt actions like jumping typically impact stealth effectiveness.

Summary

So, if you haven’t picked up on it already, keep Expected Behaviours to one sentence and use the Description and Notes to elaborate on “behaviours” you take issue with or example “behaviours” used in other games.

Frequency

Frequency (or Reproduction Rate) is so simple but so many overlook really important formatting, syntax and context. The most basic and important of which is the amount of attempts the tester or team has tried to reproduce the issue. I’m going to use capitals now, prepare yourself… THIS IS SUPER IMPORTANT AND DON’T YOU FOR GET IT!

Don’t come at me with excuses, give me something after the slash. e.g. “PlayStation 5 [10/10]”.

No “PlayStation 5 100%” or “PlayStation 5 10 times”.

“But what if it’s random?” No, is what I would say, you can do better. If it’s incosistent, don’t just leave it as “Random – 10 times”. Give context. If you really can’t reproduce the issue consistently, say something more like “PlayStation 5 [10/300hrs]”. This is a huge help in ranking an issue.

Other key points for Frequency:

🔹Always try and reproduce the issue atleast 5 times before submitting your bug.
🔹List Frequency by platform if the game is multi-platform e.g.:

PlayStation 4 [4/10]
PlayStation 5 [1/10]
XBox One [7/10]

🔹Try and keep the denominator the same across multiple Frequency examples.
🔹If you ran out of time to reproduce the issue, say so in the Notes.

Summary

Super simple to get right, easy format to follow. I can get why some may feel the need to cover up the fact that they couldn’t fully investigate an issue to get a more accurate Frequency but if you’re writing the bug, include all information and if they want to, you’re Lead can amend it when they vet the bug.

But if you’re a Lead and you’re removing that kind of information from the bug, Lead to Lead, you’re not doing anyone any favours.

Notes

There’s nothing super interesting going on here. Think of the Notes like an overflow section. The goal of this bug format is to keep the core aspects (the Summary, Description, Reproduction Steps and Frequency) short, clear and concise. In the Notes, you can breathe a little. Stick to the same formatting you’ve used in the rest of the bug i.e. ‘Single Quotes’, “Double Quotes”, Capitalisation and [Square Brackets] and add any extra info that you will help add context to your bug, just don’t turn it into an essay. You can also use it to explain why you have worded things the way you did or extra info to help explain any attached media.

Update Notes

This is one that I haven’t seen used outside of my time in PlayStation Cert-Ops but I think the Cert-Ops team get it right here. If this is a new section to you strap in!

Unless a glaring issue with the bug was missed during triage, once a bug is with the dev team, it does not change. Everything stays the same, the Summary, Description, Reproduction Steps and Frequency all of it. It’s a record. If a bug is worked on and the issue isn’t fixed when it comes back to QA, any new info is put in the Update Notes section.

Why? To keep a log of how the issue has changed over time/builds/revisions. e.g.

Update Notes

Build 1340 – Partial Fix. Issue no longer occurs in Story Mode. Issue still occurs in Challenge Mode. – CM
Build 1338 – Open. Issue still occurs as described but less frequently. Steam [2/5] – CM
Build 1337 – Open. Issue still occurs as described. – CM

However, as soon as the Reproduction Steps change significantly, set the old bug to fixed and write up a new one. If you can, link/reference the two issues.

Unlike the Notes section, Update Notes should not be considered an overflow section. Each update should be short and concise. If you need to expand upon an Update Note and you’re using a tool like Jira, use the comments section and be sure to include the full Update Note in the comments so it can be easily found e.g.

Comments

Build 1340 – Partial Fix. Issue no longer occurs in Story Mode. Issue still occurs in Challenge Mode. The UI section that gave access to the option has been removed from Story Mode as a fix but as that UI section is needed for Challenge Mode, the issue is still present there.

Why Not Change the Original Bug?

The original bug should act as a snapshot in time — a record of what was discovered, how it was reproduced, and what the impact was in that specific build. Editing that information later muddies the timeline, and QA, devs, or producers looking back won’t be able to accurately trace the bug’s history. This becomes especially important when trying to debug regressions, investigate design changes, or report trends in testing.

Instead, use Update Notes, this preserves:

🔹Traceability – Each change is recorded without overwriting past info.

🔹Audit trails – Important for compliance, certification, and performance reviews.

🔹Consistency – The repro steps you’re verifying stay aligned with the version of the build they came from.

🔹Accountability – Anyone picking up the bug later knows exactly what changed and when.

Think of it like a changelog for the life of a bug — clear, transparent, and easy to follow.

Labels

What are labels? They’re a away of associating a searchable key with an array of issues. What does that mean? It’s a difficult concept to explain without the person reading having some basic understanding but I’ll try!

Imagine you get a build in for a round of testing and you find 20 bugs in single player and another team finds 50 bugs in multiplaye. Then imagine you get a build for another round of testing were the total number of bugs in single player reduces but it goes up in multiplayer.

An (insanely) simple bug report would be:

🔹Build 1: 50 Open bugs. 30 in multiplayer, 20 in single player.
🔹Build 2: 55 Open bugs, 30 Fixed, 35 New. 40 in multiplayer, 15 in single player.

At first glace it looks like there’s progress in single player but it’s worse in multiplayer. If all the bugs are labelled correctly, you can get extra context to those changes. Lets say that the 30 fixed issues were fixed in one go due to them all being labelled with QA-Feature_Equipment and the dev noticed a connection. Then lets say that a new feature, a secondary weapon was added to the build. Coincidentally, the 35 new bugs are all labelled QA-Feature_2ndWeapon.

On re-examination, it’s easier to understand now that how labelling features gives a better understanding of the game’s health. Multiplayer is fine, it was the new weapon that is the issue.

You shouldn’t need to worry too much about labels. They should be predefined and you just add them to your bug, or your Lead will. Just remember two rules:

Don’t go making them up and applying them all willy-nilly.
Maintain the same syntax as shown in your teams documentation.

They were new to me when I moved over to Jira and boy, do I love a good suite of labels! They’re really powerful when used correctly and eventually I’ll do a separate post on my labelling system. But for QA basics, any you need to remember are those two rules and you should be golden.

Media

What is media? Media is basically anything like screenshots, videos, crash logs, test matrices etc. Anything that is helpful in adding context to a bug but is effectively a separate document.

My key advice is to get into the habit of collecting and naming your media as you test. Don’t leave it too long before creating the media and then trying to organise it. A lot of stuff can happen during testing and you may suddenly find yourself making a whole bunch of video and screenshots about a new issue that pops up and the small one you spotted mid-test gets lost in a sea of “screenshot-20250409-220144.png, screenshot-20250409-211512.png, screenshot-20250409-211655.png, screenshot-20250409-210813.png”

My next bits of advice are to “zip” large volumes of media associated with one issue as if the issue comes back for retesting and is not fixed, you need to add more media and it can get quite busy. Much easier and cleaner to have a .zip for one build and a .zip for the next.

When it comes to formatting, I like to use “Key-1234 Build-1234 Video of issue occuring”. This way, if anyone downloads the attached media and shares it with the wider team, whoever recieves it knows where/when it came from.

Other than that, you can also lean on the Notes section to help explain media if putting it all in the file name is ludicrous.

Sections I Don’t Use (And Why)

“Actual Behaviour” – What even is this? No one got back to me when I asked for any reasons why this should be used and so I’m declaring it useless. It’s all in the bug Description, it’s in the Summary!

“Platform” – I call this out in the Summary and Frequency, I don’t see the need for it’s own section.

“Environment” – Similarly to “Platform”, the setup of the “Environment” should be a part of the Reproduction Steps.

“Prerequisites/Preconditions” – I haven’t used them since leaving Compliance and haven’t found a need to. Like “Environment” they can be part of the Reproduction Steps.

Final Thoughts

If you’ve made it this far — thank you! Bug writing isn’t just about following a format, it’s about communicating clearly so someone else (who wasn’t there) can understand, reproduce, and fix the issue you found.

Over time, you’ll develop your own style within whatever structure your studio uses. You’ll learn when to be concise, when to elaborate, and how to write a bug that gets noticed (and fixed!). The trick is to balance clarity, context, and consistency. Don’t worry if you don’t get it perfect from day one — that’s what Leads are for.

And remember: every clear bug you write makes someone else’s job easier — and in a dev environment, that’s gold.

One more post to go to wrap up the Bug Writing series. See you there!

Blog Roll | About | Table Of Contents