August 12, 2008

It's common sense, stupid: Tips to Write a Good Bug Report

Writing is easy, but writing clearly is hard.
It's common sense, stupid: Tips to Write a Good Bug Report


1. Clear title - the developer should be able to grasp the essence of the bug report from the title alone.

2. One bug per report - no more, no less. reason: confusion, duplication, may be overlooked.

3. Minimum, quantifiable steps to reproduce the problem

4. Expected and observed results

5. which version of the software

6. references - like related issues

7. Pictures-- A picture is worth a thousand words!


1. Don't write generic titles
Don't just chat - document personal communications, so that the knowledge won't be lost
3. Don't assume that the developers can read your mind


ingvald said...

Also: Joel: Three Parts To Every Good Bug Report

It's pretty easy to remember the rule for a good bug report. Every good bug report needs exactly three things.

1. Steps to reproduce,
2. What you expected to see, and
3. What you saw instead.

ingvald said...

Joel again...

"When a bug is resolved, it gets assigned back to the person who opened it. This is a crucial point. It does not go away just because a programmer thinks it should. The golden rule is that only the person who opened the bug can close the bug. The programmer can resolve the bug, meaning, "hey, I think this is done," but to actually close the bug and get it off the books, the original person who opened it needs to confirm that it was actually fixed or agree that it shouldn't be fixed for some reason."

top ten tips for bug tracking (my interpretation...)

1. minimize steps to reproduce
2. only original person can close bug
5. every tested version should be in mantis
6. just don't accept bug reports by any other method than mantis
7. just put bugs in mantis
9. use mantis for new features, too
10. KISS

Bill Abbott said...

Put it in the user's voice:

What you did,
What you expected to happen,
What actually happened.

Its very nice if steps to reproduce it are available, but a clear description of exactly what the user did is probably good enough to start.

Keep it open ended. What did you expect? Don't restrict to what they saw, or heard, or felt, or tasted. Let them tell you what they expected, in their own words, pictures, interpretive dances, appetizers, etc.

Again, open ended. Don't tell them to only tell what they didn't expect. GET IT ALL. Expected, unexpected, what they're used to, whether or not YOU understand it. Get as much as they'll give you.

One of the key skills engineers DON'T learn is to accurately record things they don't understand. Reporters and scientists do it all the time. Everyone should go to Journalism School long enogh to learn how to record, draw out, clarify, even when you don't understand or can't make sense of it. Plenty of time to understand AFTER its captured.


ingvald said...

hi Bill - nice input.

i agree on the open ended capture part, especially for end users. however, for our own testers (and ourselves) this is a minimum of what we're always gonna need, whether testers do it or we do it ourselves...

for end users we often ask for screenshots in addition to what we capture in text, to get a certain amount of basic info about the problem without closing their mind too much...