May 17, 2008

A Picture Is Not Worth A Thousand Words

Occasionally, I see a bug report with little more than a picture attached.

The bug reporter is basically saying "Here's a picture.  The bug is self-evident."  But for a good bug report, that is simply not good enough.

A picture doesn't explain how we got there
In all bug reports, I want to see a step-by-step procedure on how to reproduce the problem being reported.  I don't want the  persons doing the debugging to have to guess.  And I don't want them to turn the bug report around as Not Reproducible.  That would just waste everyone's time.
A picture doesn't explain what is right, and what is wrong
I'm sure the bug is totally obvious to the person who wrote the bug report.  But it may not be so obvious to me, it may not be obvious to the person attempting to debug the problem, and it may not be obvious at all to someone reviewing bug reports some time down the road.  State what actually happened.  Use words that the reader will understand.
A picture doesn't explain the expected result
A good bug report states what was expected to happen versus what actually happened.  Maybe your expectations were wrong? A picture can't explain that. copyrightjoestrazzere
A picture doesn't help when searching
One occasionally-overlooked aspect of a well-written bug report, is that it can be easily found by a search.  If someone else encounters the same (or a similar) bug, I want them to find this bug report.  If they have more symptoms, they could add them here.  If not, they can see the current state or resolution of the bug report.  I want to avoid duplicate bugs whenever possible.  Adding text here about the symptoms, error messages, log files, and such is far more useful in that regard than a picture might be.
Is a picture helpful?  Yes, it is.  Sometimes it is even critical to solving the problem at hand.

Does the picture replace 1000 words?  No.  Not when used in a well-written bug report.