Chapter 1 : How to write a flawless summary of your bug report
On WE ARE TESTERS as well as on any bugtracker, the summary of the bug report is the first piece of information the customer (and in between the mission manager) will see regarding your bug. It is very important to have sentence that is short, clear and self-explaining.
Your reader
In order to write the best summary possible, keep in mind the following statements:
- the first time your reader (mission manager, development team, and customer) will have a glimpse at your bug report, it will be by reading your bug’s summary which is in a list full of other bugs => it must catch their attention.
- your reader (mission manager, dev team, customer) has never heard about your bug before reading your summary.
- adapt your level of language to your reader: if you know the customer is Spanish native speaker, don’t try to use the list of the most uncommon words you know in english, stick with the easy ones, those that they won’t need to google translate.
Tips for writing a good summary
Writing a good summary isn’t something we can explain with a formula. We can’t say you’re 40%; 50% or 60% right about the summary. In the end it is either good or bad. It’s all about playing with the right words so the reader gets your point.
Use the right vocabulary
It may seem not very fun to have to learn vocabulary — we all remember the long list of vocabulary from primary school and how boring it was — but guess what? The right vocabulary is the first step in being clear and concise when explaining something.
The “line of links at the top of the page” is a “nav bar” or a “header menu”.
The right vocabulary lets you get straight to the point in fewer words.
Locate your bug
In the “section” list, we provide the list of sections related to the product-to-be-tested. Always use the section that is the most accurate with regards to the problem.
For example, if you have noticed a problem with the nav bar on the home page and if the problem is spread on all the pages where the nav bar is present, you should select “nav bar” and not “home page”.
If none of the sections match your problem, select “other” and write in the summary, the page/feature where you found the bug, at the beginning.
Be precise
If you write something vague, it’s like saying nothing. Your reader will have to read your bug report entirely to start to understand the problem. And, when later, they read the summary again, it won’t ring any bells.
Don’t
section : Home page
summary : the button is wrong
Would you know which button the tester talks about here?
What does “wrong” mean?
Not clickable? Design is broken? Leads to the wrong page? Brings back to the page?
Do
section : Home page
summary : [Call To Action] the button is inactive
We recommend to use […] at the beginning of the summary if the bug needs to precise a specific area or a part of a feature or the specific object of the bug.
When writing your summary, imagine a funnel of information : [section] > [area of the section] > bug
Examples of Do and Don’t
Graphic bug:
Don’t: the image is damaged
Do: the profile picture is vertically flattened
General bug:
Don’t: cart summary before order is not as expected
Do: [cart summary before order] shipping address is not displayed
Functional bug:
Don’t: can’t see a video
Do: [Video streaming] endlessly buffering whatever the network speed
Performance bug:
Don’t: website is slow
Do: loading time of the pages are above web standards
Wording bug:
Don’t: poor Spanish
Do: [Spanish version] extensive translation mistakes all over the website.
Ergonomic bug:
Don’t: useless bar
Do: [nav bar] displayed at the bottom of the page >unnatural location
< back to tutorial — — — —— — — next chapter: Actual/Expected results>
