"Defect Report" - The Art of Writing

“The aim of writing problem report (defect report) is to get the defects fixed”

Just imagine a tester who is very efficient and skilful in finding defects in the application that he is testing but is very poor in reporting them. Is it not something like cooking a great dish but serving it in an old dirty plate that leaks and messes the dining table? What is the point of taking your time and putting your effort to prepare a tasty dish if your guests can’t enjoy its tastefulness (due to the bad way in which it is served)? The same can happen if a tester is good at finding important defects quickly but ends up logging bad defect reports/bug reports! Chances are more that the seriousness of his reported defect might go unnoticed [worst still, the defect might get turned down as “Rejected” since the programmer looking at the defect report finds it hard to figure out the bug].

Following are few pointers that can be kept in mind to effectively report software issues:

1. It’s all in a Name: Each defect should be clearly identifiable by the defect title. Keep it short, and yet the defect report title should give a descriptive summary of the defect. Use meaningful defect titles that reveal the point of the report without further reading; the key here is to create micro content that can fare well on its own. Give the maximum amount of information with the least amount of words. Time is finite and programmers/managers are infinitely busy. Blast your defect investigation result into the person reading your defect report at the speed of light!

2. You miss the Context, you miss the Defect: Each defect should be reported after building a proper context. What are the pre-conditions for reproducing the defect? What was the test environment while you got the defect? Software defects are very sensitive. They don’t show up unless all the error triggering conditions are in place and all the pre-requisites are met while setting up the test bed. Try to include all such information in your defect report. 

3. Don’t leave a Missing Link in your Defect Report: They say Waterfall Model is dead in today’s fast paced agile era of complex software development. But I would say following a Waterfall Model like approach is not that bad, always! Not at least, in case of writing down the steps required to reproduce the defect. Sequentially write down the steps to reproduce the defect in exact order. Missing to mention a step might result in non-reproducibility of the defect.

4. If it’s not clear it can get blurry at the other end: Be very clear and precise. Use short and meaningful sentences. As a simple practice, read aloud the defect report before hitting the “Publish”/”Submit” button on your defect tracking tool. If it is not clear and you are finding it difficult to understand how to reproduce the defect, chances are high that the programmer would too.

5. Tell Stories to show Defects: Defect Reporting is another area where a tester’s story telling skills can come in handy. Cite examples wherever necessary, especially if defects are a result of a combination of values. Build scenarios and present your scenarios to strengthen the importance of the defect.

6. Tag your Defect: Give references to specifications (if available) wherever required. e.g. Refer Shopping Cart module on page 137 of SRS Version 4.2.

7. Simplicity is the mother of Elegance: Keep the descriptions simple. It’s never a good idea to only use sophisticated words that everyone may not know. Keep your report description simple and easily understandable. Don’t expect the programmer to have a dictionary software running on his machine to find meaning of the highly sophisticated words in your defect report. Save such words for your doctoral thesis in English!

8. Pass Information, not Judgements: Be objective. Report what you are supposed to without passing any kind of judgement in the defect descriptions.

9. Severity and Priority: Thoughtfully assign severity and priority to the defect. It becomes easier to filter out important issues later on if they are already assigned with severities and priorities. Remember, a minor issue can have high priority and vice versa. So give it a thought before assigning a defect with severity and priority.

10. Don’t create a Mess: Hang on to your basic hygiene while defect reporting: spell-check, grammar-check, style-check. Spell-check your report, and read it for clarity once or twice before posting. An error now and then isn’t bad but a lot of error in your defect report might send a wrong signal about the credibility of you as a tester and about your defect reporting skills.
Reporting a defect is no rocket science, but it surely requires a lot of common sense. I have seen people writing mini-essays in bug reports and also the ones who report one-liners. Reported bugs should not add an overhead of understanding to the programmers but help them instead to reproduce the bug and effectively resolve it.

Source: Google, We Love Testing.