Explaining how to report a bug

August 20, 2007 7:44 AM

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?
posted by gwint to Computers & Internet (7 answers total)

It is easier to teach your app to correctly report problems than to teach users to correctly report problems, grasshopper.
posted by mrbugsentry at 8:08 AM on August 20, 2007

1. What exactly did you do? What was the URL, what did you enter, etc.
2. What exactly did you see? Exact output, not a paraphrase.
3. 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.)
4. 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.)
posted by Zed_Lopez at 9:10 AM on August 20, 2007 [1 favorite]

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.

posted by smackfu at 9:13 AM on August 20, 2007

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.
posted by indyz at 9:14 AM on August 20, 2007

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.
posted by indyz at 9:18 AM on August 20, 2007

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

• Be precise and informative about your problem
• Describe the problem's symptoms, not your guesses
• Describe your problem's symptoms in chronological order

posted by mbrubeck at 9:20 AM on August 20, 2007

Yeah, I was cribbing from Spolsky. (I just didn't remember who I was cribbing from.)
posted by Zed_Lopez at 9:40 AM on August 20, 2007