Effective Bug Reporting


#1

@bencurthoys just forwarded me an article from 1999 about how to report bugs effectively. Much of it, (in fact all of it), is still really relevant:

Here is my distillation of the article:

  • “Show Me”

“One of the very best ways you can report a bug is by showing it to the programmer. Stand them in front of your computer, fire up their software, and demonstrate the thing that goes wrong. Let them watch you … run the software, watch how you interact with the software, and watch what the software does in response to your inputs.”

Obviously we use the AnyDesk’ app to remotely view your desktops and this is one of the best ways for us to be able to see a bug in action.

Don’t have ‘Any Desk’ Installed… find out about it here.

  • “Show me how to show myself.”

"If you have to report a bug to a programmer who can’t be present in person, the aim of the exercise is to enable them to reproduce the problem. You want the programmer to run their own copy of the program, do the same things to it, and make it fail in the same way. When they can see the problem happening in front of their eyes, then they can deal with it.

So tell them exactly what you did. If it’s a graphical program, tell them which buttons you pressed and what order you pressed them in…Wherever possible, you should provide a verbatim transcript of the session, showing what commands you typed and what the computer output in response."

Obviously its not always convenient or possible to have us ‘AnyDesk’ into you, so in lieu of that, just give us as much detail as possible.

  • “Error Messages”

"If you saw error messages then tell the programmer, carefully and precisely, what they were. They are important! At this stage, the programmer is not trying to fix the problem: they’re just trying to find it. They need to know what has gone wrong, and those error messages are the computer’s best effort to tell you that. Write the errors down if you have no other easy way to remember them, but it’s not worth reporting that the program generated an error unless you can also report what the error message was.

In particular, if the error message has numbers in it, do let the programmer have those numbers. … Numbers contain all kinds of information that can be read by programmers, and they are likely to contain vital clues…Error messages, incomprehensible strings of numbers, and even unexplained delays are all just as important as fingerprints at the scene of a crime. Keep them!"

Screenshots of error messages are also great!

  • Writing Clearly

"Be specific. If you can do the same thing two different ways, state which one you used. “I selected Load” might mean “I clicked on Load” or “I pressed Alt-L”. Say which you did. …
Be verbose. Give more information rather than less…Be careful of pronouns…like “it”.

There are certain terminologies, (in Monad and Web development in general) ,which can appear to have multiple uses but actually become really specific when reporting a bug. Take something like a ‘Family Ticket’. In Monad a ‘Family Ticket’ is almost always a ‘package’. The phrase ‘Mr X Has a Family Ticket’, should really be, ‘Mr X has some tickets in an order, to which a package called Family Ticket, was applied’. It might seem really pernickety, but taking time to type out the long and verbose version of what you are reporting will actually get the problem solved more quickly.

Discount terminology is another source of confusion as Ben has pointed out, here. Even the word ‘Ticket’ itself can be the cause of contention!

The original article is here: https://www.chiark.greenend.org.uk/~sgtatham/bugs.html … its coming from a software developers perspective, rather than a support worker or customer’s, so it might seem a little passive-aggressive in its tone.

Apart from everything touched on here, there are a few other things which I can think of that are always worth mentioning when reporting a bug:

  1. The browser you are using (particularly if its a bug to do with how a page is displaying).
  2. Wether you are in customer present/ not present mode.
  3. The approximate time the bug occurred (so we can look at logs) .
  4. The account you were signed in as.

#2

This topic was automatically closed 7 days after the last reply. New replies are no longer allowed.