“We’re literary” – Buffy Summers
“To read makes our speaking English good.” – Xander Harris

Welcome back to QA Basics in game development!

In previous entries, we discussed three key attributes of a bug that help streamline assignments when time is limited. Today, we’re diving into the first substantial component: The Description

The Description should, at its core, detail the bug. It must include all relevant information that isn’t speculative or already covered in another section (for example, avoid including reproduction steps or frequency data here). The goal is to be clear, concise, and maintain a good standard of grammar and spelling. That said, if your reproduction steps ensure that anyone can reproduce the issue 100%, minor spelling or grammar issues become less critical.

Clarity becomes even more critical if you can’t achieve a 100% reproduction rate. I often say, “100% or GTFO”—a reminder not of a challenge for testers, but of the importance of avoiding a bloated Description.

Before we discuss how to manage lengthy Descriptions, let’s establish some ground rules. These formatting rules are unique to bug reports (from my experience atleast) because bugs often reference elements within the game, in the dev team’s documentation, and the hardware that connects these realms. The purpose of these rules is to clearly indicate which “world” you’re addressing. FYI, these rules also apply to Reproduction Steps, Notes and Update Notes.

Bug Formatting

‘Single Quotes’ – Use single quotes when referring to something in-game—such as a character, a menu selection, or a bespoke feature.

“Double Quotes” – Use double quotes when referring to external documentation—like the G.D.D., Technical Requirements, or meeting notes.

Capitalisation – Any reference to a generic in-game feature (one that isn’t unique or already formatted with single quotes) should be capitalised.

[Square Brackets] – Use square brackets when referencing user interactions with real-world hardware.

These four simple rules help define what the tester is describing without needing to explicitly state it every time. Below is an example that outlines the benefits.

Bug Description Examples

Unformatted – Bad

Formatted

When the user “presses the X Key on the Keyboard”, the ‘Key Card’ is not recognised and the user is unable to exit ‘The Space’. When the user presses the [x key] on the keyboard, the ‘Key Card’ is recognised and the user is able to exit ‘The Space’.

As you can see, adding the formatting really makes it clear a to when the user is pressing a button on a computer in the game compared to pressing a button in real life. You can also see that the GDD states the user should be using the in-game computer and that we’re not just trying to exit an area but potentially a specific level called The Space.

For me, these rules are invaluable for keeping bug reports clear, concise, and unambiguous. Once you’ve got the hang of them, they really help rein in those overly long Descriptions.

Also—and this might be a bit controversial—I personally think a well-written Description removes the need for an “Actual Result” section. If anyone can explain the benefit of including “Actual Result” in addition to the main Description (especially when paired with “Expected Result”), I’m all ears!

Anyway, I digress. Let’s get back to it.

The Lengthy Bug Description

Honestly? I hate them. A bloated Description can feel like a failure in clarity—but sometimes, it’s unavoidable.

So, what can you do about them?

Lean on the other parts of the bug report: Reproduction Steps, Frequency, Notes, and any attached media. These sections can do some heavy lifting.

Let’s say you’ve got an issue that happens around 53–54% of the time overall, but the Frequency rate changes based on how the user triggers it:

80% if they do it one way, 30% another, and 50% another still.

First, ask: Are these all the same bug?
If each method requires changing multiple parameters (or entire steps) of the Reproduction Steps, it might be worth splitting them into separate bugs.

But if you’re confident it’s the same bug, here’s a better approach: bulletpoint the trigger methods and their Frequency in both the Description and Reproduction Steps. Here’s an example:

Unvetted – Bad

When the user equips their primary weapon, the avatar’s materials become corrupt. This issue will occur when equipping the primary weapon in the loadout screen 30% of the time, during the pre-match spectation 50% of the time and when on the pause menu mid-match 80% of the time. The differing Frequency it occurs with in each instance is possibly due to the amount of activity taking place behind the overlaying menus. This appears to have an effect on which menu item is visibly selected and which is actually accepting input from the user.

Vetted

The Avatar’s materials will appear corrupt when equipping their Primary Weapon:
🔹In an active match [8/10]
🔹When spectating before a match [5/10]
🔹When preparing their loadout [3/10]

When more A.I. is active, input lag is apparent when making menu selections and increases the chance of reproduction.

---

Final Thoughts

This post was more difficult than I expected! I think we’ll have to revisit this topic after we’ve covered the other sections of a bug report—because honestly, I can’t effectively tackle the challenges of a lengthy Description without first showing you what the other parts are for.

That said, I think we’ve made it pretty clear that some basic formatting rules can go a long way in keeping a bug description clear and concise.

If only I’d followed that advice for this blog post!