There is the argument that some things are too trivial or too time consuming to log so lets cover what should be logged first.
- Stuff you won’t be able to deal with immediately. There are agile practitioners who argue you should be able to avoid using the bug tracking system by simply dealing with things immediately. This is worthy but not always possible.
- Things you might want to look up in the future. Decisions you want to note the justification for for example.
- Things that will take a while to complete. You can work on a case over days or weeks adding more information to the case until it’s done.
- Things you want a record of so that you can compile a more accurate list of changes when producing a release.
If you’re in a highly distracted environment (which is common in a lot of companies) then a lot of things should be logged simply so that you can remember what you need to look at in 5 minutes.
The next challenge is getting the correct amount of detail in a bug report. A good rule of thumb is to ask yourself “if I came back to this bug report in a week or a month would I still understand what the problem is?”. This isn’t simply a thought experiment. Because bug trackers allow you to record important information and come back to it when you have time this will actually happen quite frequently. It can be a month before the developer has a chance to look at the bug and if they don’t understand it they will simply ask the reporter to explain. It’s surprising how often you find the reporter cannot remember what the problem was based on the bug report.
You generally want to report enough information to reproduce the problem reliably. Not being able to reliably reproduce the problem doesn’t mean that you shouldn’t file a bug, it’s just much more convenient if you can. At the very least it’s very useful to provide what menu option you went to with the problem or the url of the page you were visiting. A lot of people refer to a window or function on the system by some short hand that they and possibly their colleagues understand but is ambiguous or simply not understood by the developer. A straight forward reference to exactly where you saw the problem is often invaluable.
There are a few things you should avoid doing when reporting bugs. In general you should avoid putting multiple problems into a single bug report. A classic problem is end users re-opening a bug to report a completely different problem. In general keeping each bug report relevant to a single problem allows you to see what progress you’re making and what is going on a lot more effectively. If everything is put onto one bug report all you can tell is that there has been a lot of activity. Not how many problems there are or how serious they were.
This doesn’t mean you should never re-open a bug. It’s just a case of checking whether the problem you’re seeing is directly related to the old bug. If a bug is closed reporting that the status text is green but it’s actually blue, that would be a good reason to re-open it. Otherwise you generally want to create a new bug. You can always mention the other bug in your report if you think it’s relevant. Most bug tracking software will actually hyperlink those references for you automatically, detecting ‘bug nnn’ in the text and turning it into a link.