D-E-F-E-C-T, Find Out What It Means To Me

If you’re in the software industry and you actually, you know, run the software (which excludes most managers, client facing people, technical writers that produce the manuals, many developers, and some quality assurance professionals whose jobs rely upon creating pretty reports with neat statistics), you’ll probably encounter an issue, otherwise known as a defect or a bug, with your application or Web site. What should you do? If you ask a developer, he’ll probably tell you don’t do that. However, you should probably log an issue or otherwise report the problem so that your organization can earnestly act as though it’s going to fix the problem.

Many organizations create elaborate procedures to trace the defect’s accountability and to standardize defect report information. Many software packages ensure that users enter the same sorts of information for a defect report, but those expensive applications do nothing to audit the quality of the report that the users enter. Some organizations just use spreadsheets and misplaced e-mails in lieu of spending money or installing Bugzilla. Regardless of what technology your organization uses, the quality of the content within the defect report is more valuable than the most rigorous procedures in handling the defect report.

For no matter how stringent the processes imposed by the software package, some users use the defect tracker software as a personal Post-Itâ„¢ notepad, logging such shorthand defects as this:


dlgEntry not updating tblUsers

Although this defect means something to the developer or data architect who logged it, the rest of the team who might not be as familiar with the code as the this developer cannot evaluate or investigate, much less retest, the defect after a developer, probably the one who logged the defect, corrects the problem. No doubt the developer thinks that this is not a bug, it’s a feature of the bug report.

By creating a well-formed defect report, you can ensure that everyone will understand the defect you have uncovered and ensure that all other people who need to deal with the defect, whether a manager who assigns the defect, a developer who recreates the defect to fix it, or a software tester who retests the fix.

To properly capture the user mindset and expectations as well as the behavior of the application, you should include the following sections in a defect report:

  • A relevant title that briefly identifies the problem and expresses it in a parallel fashion to other issues.
  • A summary that describes the current behavior of the application and what you were trying to do.
  • Steps to recreate the defect that describes exactly what you did and what values you entered to create the defect.
  • Expected behavior that describes what you think should have happened.

Many people often overlook the importance of the title of the defect, but the title displays in many table views when looking at lists of issues, so a properly formatted and written title will make it easier to understand and identify the underlying problem.

It might behoove you to determine and apply a standard titling convention to make sure that the titles contain information relevant to your organization and use parallel structure for sorting purposes. In the past, I have promoted and used the following sort of title naming convention:

Section > Window/Page Title > Issue

The title for our sample for the preceding example, focusing on the dlgEntry, would look something like this:

User Entry > Doesn't save user data

This way, when your defect lists become longer, you can sort by the title and all issues with the User Entry section or dialog will fall into place.

Most titles have strict limitations on character count, so heavily nested dialogs or pages will require some creativity to limit the breadcrumb trail in the beginning of the title. Also, remember that in many cases you can search lists of defect titles, so using standard keywords could help navigate large lists of defects.

The summary component of the defect report should contain a sentence or more about what happened. You should summarize the Web page, dialog box, or window you were using, the task you were trying to perform, and the actual result of your action.

For example, the defect sample given the preceding section:

dlgEntry not updating tblUsers

Should include a fuller summary, such as:

The User Entry dialog box doesn't seem to save the user data; when I enter a new user and then try to review that user, the application cannot find the new user.

This sentence conveys a better sense of what has happened. Although a developer might understand what dlgEntry means, most users would more easily recognize it as the User Entry dialog. This summary also tells people who cannot directly view the tblUsers table in the database what is wrong and how to see the effects of the problem.

Developers and testers will appreciate if you add the precise steps you took when encountering and recreating the defect, including test data you used. This lets the developers recreate the defects on their own, without requiring a phone call to you so you can walk them through the issue or without marking the issue as nonreproducible because they couldn’t even bother to call you. The testers can use these steps as a test case to retest the defect once resolved.

For example, to describe the steps for the sample defect, you might enter:

  1. Run the application.
  2. From the User menu, select New User.
  3. User Entry dialog box displays. In User Name edit box, type NewUser.
  4. In the Password edit box, type password.
  5. In the Confirm Password edit box, type password.
  6. Click Save.
  7. Success message displays. Note user ID number.
  8. From the User menu, select View User.
  9. View User dialog box displays. In User ID edit box, type user ID number of new user.
  10. Click View.

An error message indicates that the user cannot be found.

This comprehensive set of steps and the result provides a complete script that anyone can use to recreate the issue you found. Although it takes longer to write than shorthand, its clarity ensures that someone else can follow the same steps you did without your intervention.

Finally, the defect report should contain an explanation of what you expected to happen or what you think should happen instead of the current behavior. If you’re lucky enough to have requirements for the application, you can refer to those requirements specifically here. If not, you must capture what your expectations as a user.

This expected behavior can serve as a starting point for business analysis to how the application should behave in the situation. If the issue represents a gap in your understanding of the application’s behavior, the resolution can serve not only as education for you but also as a reference for future users. If the issue requires resolution such as a code change or configuration update, the expected behavior provides the successful test criterion.

For example, our sample defect would only need the following expected result:

When you enter a new user, you should find the user in the View User dialog box.

You should make this description of expected behavior as detailed as possible to ensure that anyone else can understand and retest the defect as necessary.

If you compare the sample defect reports, you can easily see that one provides better information.

The cryptic defect report that looks like this:

dlgEntry not updating tblUsers

could better serve the team with greater detail:


The User Entry dialog box doesn't seem to save the user data; when I enter a new user and then try to review that user, the application cannot find the new user.

  1. Run the application.
  2. From the User menu, select New User.
  3. User Entry dialog box displays. In User Name edit box, type NewUser.
  4. In the Password edit box, type password.
  5. In the Confirm Password edit box, type password.
  6. Click Save.
  7. Success message displays. Note user ID number.
  8. From the User menu, select View User.
  9. View User dialog box displays. In User ID edit box, type user ID number of new user.
  10. Click View.

An error message indicates that the user cannot be found.

When you enter a new user, you should find the user in the View User dialog box.

The second defect offers a user-friendly and easily comprehensible illustration of the issue.

By making sure that defect reports contain good, informative descriptions of defects, you’ll reap benefits that mere technology would provide. Complete, well-formed defect reports will ensure that all team members can review, recreate, and retest defects easily, so your team can pass tasks easily.

Complete defect reports also prevent duplication of defect reports. Users can review existing defects and can more easily determine whether someone else has already uncovered the issue they encounter.

A more detailed and properly written defect report will better serve your organization by creating an artifact that can stand alone and is less subject to interpretation or dependency upon a single person’s unwritten knowledge of the issue or application for comprehension.

The benefits aside, some resist or simply overlook creating a well-formed defect report because it can be time consuming during the issue’s creation. This time, however, will be recouped at every other stage of the defect handling process and will ensure that, two years from now when some junior developer who’s just started starts marking issues resolved en masse, you have the information required to actually retest the issue and reopen it.

Comments are closed.


wordpress visitors