, by  Tom Simnett

It Doesn't Work

Why detail matters.

“The site doesn’t work.” “What do you mean, the site doesn’t work?” “It just doesn’t work.” “So what is it doing that it shouldn’t be doing?” “When I go to the site, I can’t do X.” “But when I go to the site, I can do X.”

To a developer this is an all too common dialogue between someone looking over the site - usually someone non-technical, and definitely someone who hasn’t read up on Reporting bugs effectively.

After development comes testing, and during testing, bug reports are made. If the bug reports are unclear in any way, then it takes more time to fix them, because it takes more time to decipher their real meaning. So what this article is about is understanding the core elements of a good bug report, and why “It doesn’t work” is bad.

From the perspective of a developer, a good bug report consists of a specific set of things that must always be there in order to be able to replicate it. Without the ability to replicate a bug, the chances of it being fixed are very slim. The above article by Simon Tatham, a very well regarded developer, of PuTTy fame, is probably one of the best groundings I’ve seen for writing good bug reports for software, and it extends to web applications and sites too. The first of these things is a concise but clear summary of the bug. One line is enough - just something that describes the issue, eg. “Firefox 3.0.3 prevents upload of multiple files in new messages”. That’s a good summary that with some additional information as described below is the formative part of a good report.

The concept of “Show me how to show myself” is crucial here. What’s needed is a step by step set of directions by which you came to see the bug. The developer may well not have used the application in this way, and didn’t expect it to be, but users will always do the unexpected! If the issue is a display issue, take a screen shot, and include the whole window, not just a bit of it. If it’s a browser issue, and this happens a lot on the web, the developer needs to know which browser the issue happens in. If the same issue happens in every browser, one screen shot will do, but a comment to that effect is absolutely necessary. There are also some key facts that should be included with any and all bug reports: Operating System, Browser, Browser version, URL on which the error occurs. Some other useful pieces of information, depending on the bug report are: Flash version (or that it’s not installed), JavaScript status (on / off). If you think there are any more, there probably are, so feel free to comment on this article.

So, to conclude, we need a good summary (usually marked down in a subject field if you’re using a bug reporting system), a set of facts about the machine you’re seeing the issue on, a clear set of instructions on how to reproduce the bug, any additional information the developer might need to reproduce the bug, and if you can, a screen shot or set of screen shots to show the developer the problem you’re seeing.