There is an art the problem reporting. It could be a science, but I think of it as an art as then it remains fluid, adaptable to the problem at hand. Semantics aside, your task as the reporter is this:
To report the problem in such a way no further contact with you is required for it to be resolved.
That's it. If you report your problems well enough, with detail the person who's helping you fix it needs to dive in and work out the problem and the solution right away, you have done your job and you have done it well.
When filing a problem report, include as many of the following suggestions as possible, if they're applicable:
- What operating system or browser you're using.
- What application is being used.
- What version of the application is being used (if there's a Help/About menu, look there).
- What the symptoms of the problems were.
- Exactly what you did to evoke those symptoms (including, if it was part of data entry, what data you put in each field before getting there).
- What error, warning or informational messages you saw on the screen – include a screen shot if possible.
- Whether it is reproducible.
- If there are any logs which could contain useful information, provide them or say where they can be found.
When working with clients, I received problem reports frequently. Here's a recent example of a problem report which didn't provide anywhere near enough information to be useful:
"Since the powercut, we can no longer see the database 'wibble' using phpMyAdmin."
After working with them for an hour or so, with many emails going back and forth, the problem was finally resolved. Over the course of the email exchange, more information came out which was vital in diagnosing the problem.
Here's an example of how the original problem report could have better been communicated and thus a resolution more speedily obtained. I've numbered the parts as they apply to the above list:
"We're having a problem accessing one of our databases using phpMyAdmin(2) via Firefox(1). When we go to view the tables in database 'wibble', nothing displays(4)
This is reproducible(7). To reproduce, go to http://phpmyadmin.ourcompany.com/, click server 'ourserver' and then click database 'wibble'. You'll see there are no tables listed on the left hand side(5).
I don't know if it's related or not, but when having clicked our server 'ourserver', there's an info message on the screen which says 'Your PHP MySQL library version 5.0.51a differs from your MySQL server version 5.1.45. This may cause unpredictable behavior.'(6)"
Using the above information, I can immediately work on narrowing down the problem. I know the server which is demonstrating the problem (phpmyadmin.ourcompany.com), where it's connecting to (ourserver), the database it's trying to connect to (wibble) and I know there's a possible MySQL client/server version mismatch. Using all that, the problem was identified and resolved within fifteen minutes. The bulk of the time – and thus cost to the client – was spent extracting the information in the first place.
So please, bookmark this page or print out the above list and stick it on your wall. Do whatever you need to ensure you make useful problem reports. Your systems or application team will appreciate it.
