Use “5 W" to write effective defect descriptions

Effective communication, like effective testing is a skill. So, like all other skills, it can be learnt. Writing up a good defect report is certainly one area where learning effective communication can help tremendously.

For the scope of this post, let’s focus on the Summary (or Title) of your defect report. 

What should a good defect summary include?A defect summary should provide brief insight into the problem you are reporting.

• It can be as short as a single sentence or a couple of sentences, depending on the length of Summary field in your defect reporting.
• It should be specific, clear and concise.
• It should provide enough details for all stakeholders (or consumer of your defect report) to understand the defect and act on it.

What’s this “5 W” and how it can help?There are 5 possible questions that the readers of your defect report will like answers to:

1. What
   
2. Who
   
3. When
   
4. Where
   
5. Why

Let's call these "5W". If you answer these satisfactorily in the summary, it can convey necessary and sufficient data on the defect that you are reporting.

Let’s understand each one in depth:

• What?
  What is the actual result? What is the problem noticed?
  
• Who?
  Which user? Admin? Normal user? Someone with special privileges or role?
  
• When (which action)?
  When does the problem occur? By performing which actions can the defect be replicated?
  
• Where?
  In which part of the application - screen / module / user story?
  
• Why?
  If you are 100% sure of root cause of your issue, you could mention that upfront, so developers will have some pointers to start debugging on.  Use this option with extreme caution. There’s a possibility that putting   this information up front can mislead the developers, too.

We can combine all these questions in a meaningful sentence as:

Defect Summary Template

Using this template can tremendously simplify defect reporting task. Here are few more guidelines to go with it:

• All of these questions are optional except for “What”. Obviously!
• Be specific in your reporting: “Null reference exception” is much more informative than “an error occurs”.
• Use active voice. The sentence becomes shorter and clearer.
• Keep “What” not “when” as your focus, as the subject of your sentence. Compare “Null reference exception occurs on trying to search for a value that does not exists in Products table.” with “When user provides a non-existent value in search field on products table, she gets a null reference exception.”

For some examples, check these:

• “Object not found” Javascript error when trying to save appointments using the web version of e-Organizer.
• Application crashes with *** exception when Admin tries to inactivate multiple users from User Listing screen.
• “Could not load your list” error when user tries to add a to do list item for today on the Android e-Organizer app.

When we realized in our big teams that different reporting styles often led to confusion and multiple cycles of defects going back and forth between qa and dev teams for lack of understanding, we resolved to use this template and are happy with the results:

• Our defect summaries are more informative and follow a standard pattern across all levels.
• Defects are easily searchable as there are similar keywords being used.
• Management gets better picture of the criticality of issue just by going through the summary.

Do try this trick yourself and revert back with your experience or comments.

Thanks for dropping by!