Keep it clear & concise

There's a lot to consider when writing a bug. At the very top of that list is communicating the issue both clearly and concisely.  A big part of our job as QA professionals is distilling and conveying complex information into clear messaging.

In order to be clear and concise we need to be very intentional with our word choice. When writing a bug we need to understand who we're writing this bug for.

The audience who will be laying their eyes on your bug is often:

1. 1. Those who attend the daily bug triage meeting
   2. The producer of the particular pod the bug is assigned to
   3. The developer assigned the bug
   4. Other testers who will be testing the fix implementation

The goal is to use the fewest words possible yet still effectively convey the issue. Think of it as an economy of words - brief yet descriptive enough for anyone to quickly grasp in a 2 seconds. To accomplish this, we need to use plain language and be consistent with our terms. In regards to terminology, one process I recommend is making a reference glossary, a shared unified document, and keep it up to date (See article: Documentation as Knowledge Sharing).

Bug food for thought

When writing bug summaries, it's important to consider what's the most vital information our audience needs in order to understand the issue. We also need to think about the order of information in which to deliver it most effectively. What we say at the beginning of the summary gives immediate context and what we end with is the specifics of the issue.

The format I use looks like this:

[Feature] Bug subject followed by specific details about the issue

I'll explain how to write an effective bug summary into two parts:

• 1. Using [brackets] to help identify the category
  2. The actual bug summary which describes the issue

1. [Brackets] help identify

First, the brackets contain the name of the feature, category, page, or type. If you're executing a test plan for a specific feature, use consistent naming here. All of the bugs you write for that feature should have the same name contained within the brackets. These essentially function the same way as keywords or #hashtags.

This makes it easy for someone to scan and know what team and/or feature this bug is for, whether it be an issue for design, art, sound, or gameplay. In some cases, you can even double it up to call out both a feature and sub-category (e.g. [PvP][Sound]). Using two groups of brackets indicate that the bug is within the PvP feature, but is more specifically a sound issue.

As you continue to work with different teams and throughout milestones, you'll grow more familiar with every aspect of your role and be able to narrow down specifics like these.

2. What is the issue and when does it a occur?

Next, we want to immediately answer the what and follow with the when. If it helps, you can also think of these as the subject and the condition. A bug often is a subject that occurs under a certain condition.

A simple mental model to use is:

Ask yourself what is the issue and when does it occur?

With that said, our goal is to write our bug summary using as few words as possible, while retainining all of the critical information at a glance.

In order to achieve this, we want to hit each of these points:

1. Clearly state the issue with professional language
2. Include details that may be important
3. Avoid unnecessary details or filler words

2a. Wording order matters

Additionally, the order of our wording matters. In many cases, it's a good idea to lead with the what to make it easier to read and gain context quickly. In general, the first few words of a sentence usually have the most impact.

The what leads the when:

• • [UI][Navbar] Claim Reward button is unresponsive when switching to a different tab

An exception of when we want to swap this around is when we want to emphasize the action:

• • [UI][Navbar] Double tapping the Map button will cause all nav buttons to become unresponsive

That reads more clearly compared to this:

• • [UI][Navbar] Map button causes all nav buttons to become unresponsive when double tapping

Let's say we found a bug while testing a big update for a guilds feature that is in development. We found a bug with the chat not being clickable; but what caused it? Further testing shows it happens after you edit your guild details.

Great! Now we have enough information to write a bug.

This is a good bug summary

• • [Guilds 2.0] Chat text input field is not responsive after editing guild details
    • What - Chat text input field
    • Issue - not responsive
    • When - after editing guild details

This summary clearly states what the issue is in the beginning while expanding on what behavior led to the issue. It uses professional, technical terms and is brief yet descriptive. It answers both the what and the when.

*Sidenote: In the bug description I would also mention whether the bad state is recoverable or not which will affect how the bug is prioritized.

These summaries could use more love

1. [Guilds 2.0] Chat is broken - This doesn't use professional language and is missing specific details
2. [Guilds 2.0] Tapping on chat doesn't work - This is a little better than the last; at least I know the interactive element is not working
3. [Guilds 2.0] Editing guild immediately breaks chat - This is closer but can be improved by mentioning what specifically about chat is not working as intended. Also, avoid unnecessary words like adverbs; remove the "immediately" to keep messaging concise.

Clear & concise language builds trust

We want to avoid making our audience do the guesswork of what the issue is and what the details are. The language we use for communicating an issue that is clear, concise, and informative not only helps others triage or investigate fixes, it ultimately helps builds trust and confidence in your team.