Entering Defect Reports

Its something we do all the time, and I've been doing it in various incarnations of software for years now, but I rarely just give detailed thought to it until I went into an interview recently and was asked - "What do you put into a Defect Report?"

At first I was thinking, sure I know this and could easily list off many items that should be in there, but then I started wondering what is the purpose of some of these things I do and write down.  Sure I do them because I know it gets the right detail on the problems listed, it also makes it easy for Developers or anyone else to read the reports, I have been doing them for a long time, and I have evolved certain things over time.  So in order to put it down, and to have some place to also answer people who seem to ask this time and time again in the forums I give you my List Of Things To Be Included In A Defect Report.

1. Title - the title should be 20 or 25 words, in some cases its about the length of the title field in certain software, but its also good to be concise.  Make the title useful in case you are searching for defects and the title is a field that is returned, you want to be able to find old defects easy and know by the title what they are about.  It's also useful to other people who may be searching old or open defects, if they can tell what the defect is for then so much the better, it avoids much opening of defects to review.  Usually I put in error messages, if short, or a small description of what the error is.
2. Description - this can be a lengthy overview of what the issue is, sometimes its useful for detailed defects so there is something to check over before getting into the nitty gritty, but the description also contains many other things which shall be noted shortly.
3. Steps to Reproduce - this is vital.  If you want someone to be able to fix the defect they may need to reproduce it, without knowing how you'll get visits by people who want to know what you did.  Or it may just be closed as unreproducible, or sent back to you for more information.  Make sure you run through the steps a few times, make sure nothing is missed and that other people can do it on the same machine, or a different one if that is your company's environment.  This should be included in the description.
4. External Files - screenshots, core files, dumps or whatever else may help someone triage the issue should be included in the report, if possible, or note a location on a publicly accessible area, or at least an area accessible by your co-workers, where the files can be found.  These are necessary to determine where issues have come from, or may be needed for someone to see the error messages, of UI issues, you report.  This should be included in the description if not attached to the report, its often nice to note this information is attached.
5. Platform, machine type, operating system - anything else specific about where the issue occurred.  Many defect systems have this as pull down information available when entering the defect, if not put this in the description, and sometimes its useful in the Title as well.
6. Why its not a duplicate - if this is similar to an existing issue but not the same, note why in the Description.  If its related to an existing one, make sure to link the new one to the exisitng defect so there is a trail for people to follow, many defect systems allow this otherwise add it to the Description.

There is usually more, but the core information is what is really need to make the report complete, easy to understand and most importantly searchable within the defect system.  Searchability is a very important part that gets overlooked, if the issue ever comes up again you want to make sure the information is easy to find so you avoid duplicates, and most importantly if its been fixed you can check and see if the fix is still valid, in which case you have something entirely new.  Probably.