10 Tips to Avoid Writing a Bad Software Defect Report!

“Software” and “defects” are like two sides of a coin. If you start developing software, chances are very high that you will (although unintentionally) end up leaving some defects in it. Defects in software are almost unavoidable. Software defects are like Christmas Combo offers where you get something for free with the purchase of some Product! In case of a Christmas Bonanza offer you might throw away the free gift if you don’t like it [without spending anything extra!]. I hope, software development was as simple as that! In case of software development, you just can’t discard the unwanted defects as simply, without investing time, effort, money and whatnots!

As it has been said a million times - even (so-called) thorough testing cannot produce a 100% defect-free software. As long as there would be softwares there would be defects in the software. And as long as testers would keep finding defects they would have to report it in some form of Defect Report/Bug Report, so that further actions could be taken on the defects. As Dr. Cem Kaner puts it - “The aim of writing problem report (defect report) is to get the defects fixed”.

Just imagine a tester who is very efficient and skillful 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].

The work of a software tester on software projects is much like the technicians at a diagnostics center do. There is no scope for ambiguity when a medical diagnosis is reported. Before a technician reveals his diagnosis, a lot of symptom analysis, critical thinking, cause-effect analysis, syndrome of related diseases and mind work goes into it. A diagnostics technician has to be very accurate in reporting the problems as he diagnoses. “Patient XYZ has perfect symptoms of acute dual renal failure” might kill the patient just out of shock. In any field, effective reporting is much of an art.

Similarly, when diagnosing issues with software while testing, there is hardly any scope of ambiguity. As testers, we have to keep in mind that each bug reported involves some work for programmers. They have to understand the context of the issue, try to reproduce it and resolve it after it is reproduced. Unless your defect report is clear and precise, the programmer might find it a tough call to reproduce the defect. And unless the programmer is able to reproduce the defect, there is not much he can do about it to fix it. But non-reproducibility of the defect at the programmer’s machine does not mean that the defect is gone! It (the defect) is still sitting there (in the code, the design or the architecture of the project). And there begins the problem. Many a times, a project manager needs to understand what are the severe issues open and manage the project accordingly. But he might miss to consider the severity of your reported defect, as it was badly reported in the first place by you and the manager can’t reproduce it!

For this, testers must distinctly and succinctly report each of the finding with appropriate severity and priority assigned. [Note: When I say that your defect report must be with appropriate severity and priority, you (the tester) must understand that these are perceived severity and priority and are subjected to change in future if the person evaluating this defect (can be the system analyst, your test lead, the test manager, the project manager) thinks that a different severity/priority would be more appropriate under the given context.] Suppose you are a programmer and you see a bug report stating, “The Parser is unreliable” or “The values in the City combo box are not proper”. How would you react to it? Words like *unreliable* and *proper* are relative. What is proper to me might not appear as proper to another tester. So use of words like these can make the defect report ambiguous and the programmer reading the report can get confused!

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 microcontent 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.

Happy Testing...

Related Article: How to Sell a Bug

Further Reading:
Writing Effective Bug Reports by Elisabeth Hendrickson

Share on Google Plus

About Debasis Pradhan

Debasis has over a decade worth of exclusive experience in the field of Software Quality Assurance, Software Development and Testing. He writes here to share some of his interesting experiences with fellow testers.

6 Comments:

  1. I have few observations –

    1. You have not included definition of “bug” or defect… What is your definition of bug/defect? Is bug same as defect?
    2. Point # 4 says that defect report needs to be clear and precise. Point # 6 says, tell a story to describe a bug. I see that these two contradict. A short, precise statement is about objectivity where story telling has mostly been narration of personal experience. Story is often descriptive. An example of precise (as close as it can get) is a court order or a Law or a legal document – these can not be in a story format. When you tell a story, you leave some aspects of narration to “manipulation” and interpretation.

    Here are few points that you might want to add to your 10 points – extend them:

    1. Know your audience – who is reading/fixing/verifying the bugs. Write the bug report so that they understand and appreciate the report
    2. Sell your bug- According to Dr Cem Kaner’s famous article “Bug advocacy”, a best tester is one who gets most bugs gets fixed. Bug report is like an “ad” – make the report so attractive that developers pick the bug for fixing without much hesitation. Make the bug and its effects more explicit. Motivate the buyer of the bug.
    3. Clearly Isolate the bug - The list of steps to reproduce – has to be “bare” minimum. Smaller the number of steps better is the defect report. One way to create “slim” report is to write all that you did for getting the defect then go on removing one or more steps to see if the defect still appears. In other words, from a defect report containing 15 steps to reproduce, iterate through steps each time removing one step to see if defect still appears. There are two advantages of this approach. One, you will exactly (to best of your abilities) know the steps (and the sequence) that causes the defect. Second, while iterating, you might also discover other related bugs.
    4. Don’t make the defect report big and complex. That will give developer an excuse not to fix the bug.
    5. Don’t stop at bug, poke around the bug (bugs live in colonies, they come and go together) and describe various effects of the bug.
    6. Help the developer – report a bug as you report “missing thing”. Provide all related information so that developer is better equipped with isolate and fix the bug.
    7. Differentiate between “bug” and “its manifestations” – cause and effect.

    ReplyDelete
  2. @ Shrini,

    First of all let me express my happiness to see your comment on my blog post! It is a privilege to be commented by testers like you and hence thanks.

    1. I use "bug" and "defect" almost synonymously in my blog posts. Having said that, I understand that "bug" is a rather wider term that covers anything that has potential to "bug" someone, who matters in a software project [I owe this understanding to James Bach and Michael Bolton]. A software "bug" need not have to be a software "defect". There are different views and opinions on using the terminologies bugs and defects. So to avoid confusion, I prefer using "bug" and "defect" synonymously as of this point of time. However, I am curious to hear your definitions of bug/defect. Are they same in your definitions. If not, would you mind sharing your definitions for these two terms. I am interested to learn your definitions.

    2. #4 says a defect report should be clear and precise and #5 says tell stories to show defects. I am extremely sorry if they sounded contradicting. It must be my mistake to convey my point correctly here. Anyway, please let me clarify. When I say tell stories, I actually mean to include scenarios where this defect can be most devastating and result in most severe consequences.

    Thanks for including your points to write a good and effective defect report. e.g. Isolating the defect is very very important. If the defect can be reproduced using 7 minimum steps, it is always good to keep them 7. Discarding the unnecessary steps from the defect report requires some analysis and can result in a light-weight defect report, which is easier to scan and reproduce by the programmer.

    Thanks once again for spending your time reading and commenting on the post. Happy Testing...

    -Debasis.

    ReplyDelete
  3. I think these r the confusing terminologies and context you and shrini where telling in some other post in the blog.any way nice post and thanks to shrini too

    Regards,

    raji

    ReplyDelete
  4. Interesting read and interesting comments.

    I agree with Srini about 'selling your bug'!

    Here are two more ways you can make your defect report stand out from the crowd, and enhance its chances of getting fixed.
    1. Make a business case.
    2. “Show”, don’t “tell”.

    Intrigued? Read http://www.effectivesoftwaretestingblog.com/2010/06/make-your-defect-reports-stand-out-in.html to know more.

    Happy reporting!
    ~Varada

    ReplyDelete
  5. Hi
    I'm working as Testing engineer in middle level company.I need a free bug Tracking Tool .Can anyone please guide me.p.pradeepit@gmail.com

    ReplyDelete
  6. These are great tips in writing an effective bug report. Those who are tasked to do so are surely grateful of these strategies. Thank yu for sharing.

    ReplyDelete

NOTE: Comments posted on Software Testing Tricks are moderated and will be approved only if they are on-topic. Please avoid comments with spammy URLs. Having trouble leaving comments? Contact Me!