Comments on: Explaining how to report a bug

Question: Explaining how to report a bug

gwint — Mon, 20 Aug 2007 07:44:43 -0800

I'm having a few non-technical people test a webapp. What's the best one pager you've seen that explains the proper way to report a bug to a developer?

By: mrbugsentry

mrbugsentry — Mon, 20 Aug 2007 08:08:20 -0800

It is easier to teach your app to correctly report problems than to teach users to correctly report problems, grasshopper.

By: Zed_Lopez

Zed_Lopez — Mon, 20 Aug 2007 09:10:13 -0800

What exactly did you do? What was the URL, what did you enter, etc.
What exactly did you see? Exact output, not a paraphrase.
What did you expect to see instead? (Some of the time this'll be a stupid question, when the behavior's an obvious error; much of the time it'll be relevant to identify just how the software violated the user's expectations.)
Don't diagnose, just report the above.

And it is a huge help to have a debug setting that saves each request and response of a user's session in their entireties so you can play them back (and having this could simplify what you have to ask of your users in reporting.)

By: smackfu

smackfu — Mon, 20 Aug 2007 09:13:42 -0800

I think the key point is to capture actual vs. expected results. For instance, here is the Apple bug format, some of which may be unneeded for you:

Summary:
Provide a descriptive summary of the issue.

Steps to Reproduce:
In numbered format, detail the exact steps taken to produce the bug.

Expected Results:
Describe what you expected to happen when you executed the steps above.

Actual Results:
Explain what actually occurred when steps above are executed.

Regression:
Describe circumstances where the problem occurs or does not occur, such as software versions and/or hardware configurations.

Notes:
Provide additional information, such as references to related problems, workarounds and relevant attachments.

By: indyz

indyz — Mon, 20 Aug 2007 09:14:53 -0800

This is a bit over one page, but it is generally non-technical and easy to understand.

Zed_Lopez's advice is almost verbatim from a section of one of Joel Spolsky's essays on bug tracking. Most of that article is for the technically inclined, but it might be worth excerpting.

By: indyz

indyz — Mon, 20 Aug 2007 09:18:33 -0800

Oh, mrbugsentry: Getting an app to self-report things like crashes, database failures, etc. generally isn't difficult. Getting an app to report incorrect output, unexpected behavior ("I click on 'New Order' and it open the last order I was editing"), or matters of preference ("The input form is completely non-intuitive") can be anywhere from difficult to downright impossible.

By: mbrubeck

mbrubeck — Mon, 20 Aug 2007 09:20:57 -0800

Some excerpts from How To Ask Questions The Smart Way might help. In particular:

By: Zed_Lopez

Zed_Lopez — Mon, 20 Aug 2007 09:40:35 -0800

Yeah, I was cribbing from Spolsky. (I just didn't remember who I was cribbing from.)