Crispy Mod Tester's Handbook tutorial

Writing a Bug Report: The Bug Summary

The bigger the project, the more important the summary. The purpose of the summary is not only to give a concise description of the bug, but also to provide keywords that will allow the same bug to be found in the database at a later date. The below example is a fairly professional method of doing it. Cherry-pick any useful information you find in this section, but it doesn't necessarily have to be replicated. If you have testers that won't be able to follow a single format, use a system that you know will be adopted readily and can work for your team.

A typical summary in a good professional bug database might look something like this:

[GFX] E1_L02: Emergence > Docks - Northernmost crane model has incorrect texture (black)

This summary contains a vast amount of information that tells me, in just one line:
- what area of development the bug affects
- its location within the game
- which part of the aforementioned location if affected
- exactly which asset is affected
- and the symptoms the issue is presenting

Here the issue is that an environment model (a crane) is showing up as completely black in-game for some reason. The tester may or may not think they know the reason for this, as far as the summary goes this is irrelevant, the focus needs to be on communicating the essential pieces of information in an objective, clear and searchable format.

[GFX] E1_L02: Emergence > Docks - Northernmost crane model has incorrect texture (black)

I have added some colours to the example summary to highlight the different key areas. When using a basic (usually web-based) bug database or forums, both of which rely heavily on text-based searches, the more information you can put into the summary line, the better. On a forum, the summary line will obviously be the title of the thread.

[ ] : > - (structure)
These symbols are used to give the summary a uniform structure and allow the eye to locate different pieces of information quickly. Every bug always includes certain items of info, and these items always appear in the same order. The symbols are there to separate these pieces of info and to guide the eye through the summary line. When creating your summary format you can use any symbols in any order, so long as they are easy to remember and do the job of making the summary clear.

GFX (category)
To help with searches and search filters, you can choose some important information to put at the beginning of the summary. The category of the bug (i.e. which area of functionality it affects)
is very useful, especially for developers trying to locate bugs that affect their own work. With this information at the beginning of all bugs, I can search via a keyword like "black", and then alphabetise all the results to bunch up all the bugs by category from 'AI' to 'SFX'. If I see this bug in a list of perhaps 20 other bugs, I immediately know that this one in particular is a graphics issue, so as a reader I am well situated to understand the rest of the summary that bit better.

E1_L02 / Emergence / Docks (location)
This information leads you through the game to the location of the bug. In this case you have the location of the bug within the game world itself: "E1_L02" means it is in the 2nd level of the first episode, "Emergence" is the title of the level/mission/quest, "Docks" is the actual physical location within the game world. It's important to have both "Emergence" and "E1_L02" in the title because while the name of the level is easier to remember, the label will be more useful when searching through folders or code and it also contains information about its location within the game's progression flow.

This part of the summary isn't only for locations within a level, though, it is used to give information about the location of the bug within the game.
A bug could be located within a particular feature: "General: Classes > Soldier -"
or a menu: "Front End: Options > Sound -"

Northernmost crane model has incorrect texture (black) (summary)
Although the summary is only 7 words long, it contains 4 adjectives to link the 2 nouns (the 'texture' and the 'model'). There is information about what generally is affected (a model of a crane), which specific crane model is affected (the one furthest north), and how specifically the model is affected (that the texture is somehow wrong and showing up black).

A less meaningful way of summarising the bug would be "crane in docks is black". This simply doesn't convey as much information; it doesn't tell an artist or level designer which of the multiple cranes in the docks area has an error, and it doesn't describe the error in much detail. Saying the
crane is black could mean that it is in shadow and there is a problem in fact with the lighting in the area.

Don't be afraid to add keywords in parentheses if you think they will help other team members find the bug in the database. You don't have to masterfully work them into the summary sentence, it's fine to add them in brackets so long as the meaning is clear. Finally, if you can economise the word count in the summary without compromising the perceived meaning, it helps to keep things short. Removing superfluous words like "the" and "is/are" and letting an adjective or past participle follow the noun is usually acceptable. You can also sometimes eliminate "which"/"that" by use of the gerund/present participle.

E.g. "The door is broken before the player activates the switch which stops progression" could be turned into:

"Door broken before switch activated, blocking progression"