I’m a programmer. Which means I get to fix my code (sometimes) and others’ code (far more often than I would like). As such, through my work, my projects and occasionally through this blog, I get numerous requests to fix this or that thing.

Believe me, I want to fix the issue. Never doubt that.

However, I can’t fix the bug if I can’t reproduce it on my end. This is the first and foremost rule to remember when sending in bug reports to anyone.

It’s Broke!

Something like this:

Dear Programmer:

It doesn’t work! Help!

Frustrated

is pretty much guaranteed to have zero results.

So first of all, what would I need to know in order to find the same problem? For starters, all operating systems, programs, and their versions. So let’s say there’s a problem with displaying one of my pages on this site. The basic starting information, then, would be:

• Operating system: Windows, Mac, Linux, other?
  • version? Win98? XP, Vista? Mac OS X? Fedora, RedHat, FreeBSD? Ubuntu 6.06?
• Browser: Internet Explorer, Firefox, Opera, Safari, Konqueror
  • version? IE6? IE7? FF 1.5.06? Opera 9 or earlier?
• The actual page on which the error is spotted. This means the URL. This does not mean “Your site is broken.” This means “On http://a.random.site/somepage/specificpage.html there’s a problem.”
  • Sometimes a page is not arrived at directly but with some intervening steps. For example, let’s say there’s a starting point with options, and several particular options were selected, but then on clicking submit, a bad page showed up. Describe all steps taken to reach this page

I cannot begin to count the times I’ve been told a particular page doesn’t work and not been given the basic steps to arrive at that page. I very rarely have simple pages. I have database and choice driven pages. This means the possibilities are usually much wider than simple descriptions can cover. For example I’ll get email that says “The foster dog page is broken!”

Upon further query, I’ll find out that it’s a) the foster page used to view the ones currently in a kennel (as opposed to, oh, the page that shows the currently available foster dogs, the foster dogs currently at the vet’s, the foster dogs currently on a sick list, the foster dogs previously adopted, the foster dogs slated to appear at this promotional event…I think the idea here is clear) and that b) most of the dogs show up but one dog is missing (as opposed to, no dogs are listed, a particular kennel never shows dogs even though three are there now, etc).

Yikes.

A real life example

Here’s another one I had recently, names and sites deleted to protect the innocent. I’m not trying to pick on the person at all, but I do want to illustrate the problems that arise with uninformative bug reporting:

hi, i’ve installed the plugin @ [site]
but it doesn’t work. Do you know why?

Hmm. I replied back:

I would need a little bit more information.
Do you get the admin panel after putting it in? When you look at the options panel, is there a favicon option?
If so, when you give it the location of the favicon, does it appear below after you enter it?

I need more detail like that…or did you unpack it in the plugins directory and nothing happened? Tell me everything you did.

The reply:

> I would need a little bit more information.
> Do you get the admin panel after putting it in?
yes

> When you look at the options panel, is there a favicon option?
sure

> If so, when you give it the location of the favicon, does it appear below after you enter it?
no, nothing

Hmm. So the little favicon doesn’t show up in the admin panel after entering it. That means the system can’t find it, so it will not even try to use the favicon. I check the site he’s given me, and realize that it can’t be his site, it’s got a favicon but not through my plugin. After this digging around, I ask him:

>> If so, when you give it the location of the favicon, does it appear below
>> after you enter it?
> no, nothing

OK, I attached a picture of what my options look like after I enter my favicon name. Notice how it shows the “DR” there? If it does not show the favicon there after you enter the name, it could not find it. So I think the problem has to do with giving it the right name, which will depend on a few factors:

How is your wordpress installed? Most people install it right in the root directory, or they put it in a subdirectory. For example you can see in my snapshot, that my blog is in a subdirectory called wordpress and my favicon is there too. If I wanted to use a favicon that was not in my wordpress directory (whether that directory is in root or in a subdirectory), then I would need to specify the full path. Using mine as an example again, let’s say I wanted to use a favicon from another directory, favicons/current.jpg maybe. Then I would have to put down http://digitalramble.com/favicons/current.jpg because now it is not in the wordpress directory. Does this make sense? Once the plugin can find your favicon (as shown by being able to display it here after you enter Update Options) then it can set up your wordpress blog properly.

By the way, I went back to your site to look it over, but [mentioned site] does not seem to have a word press blog (nor a favicon) on that actual page, although I found one from the little notes on the side (under [section name]) and that wordpress blog there has a very nice white “i” in a black box for its favicon. However, that site doesn’t seem to be using the plugin (I don’t see the modifications it would make to the element on that page). If I’m barking up the wrong tree there, just let me know.

Notice that I have to account for several possibilities. Is it a default (at the root) Wordpress installation or is it set up in a sub directory. Notice that I poked around and could not even find his page.

Unfortunately, he replied to the above with a simple repetition of where his actual WordPress blog was, without replying to my questions above. (To be fair at this point, I don’t think English was his native language.) So I tried once more:

OK…can you show me where your favicon is? For example, mine is at
http://www.digitalramble.com/wordpress/favinit.gif
and if you go there and look at it, you will see it. Whether or not the plugin is
working, a favicon must be visible this way with the http address.

Also, can you go to the General Options in the Admin Panel, and tell me what it says for:
Wordpress Address (URI)
and
Blog address (URI)

He replied with:

mine is @ [complete url]/favicon.ico but it gives me error 404, that’s why it doesn’t work

After banging my head on the desk for a while, I replied

Okay, and if you have either favicon.ico or the complete http entered into the favicon option then you are using the plugin correctly.

The 404 error means one of two things. First, that the file is not actually there. That is, there is no file at all by that name in that directory. Perhaps it got deleted, or perhaps you uploaded it into a different directory after all. The second possibility is that the file is there, but does not have the correct read permissions set.

Did you use ftp to put the favicon.ico file up there? Try using ftp again and list the contents of that directory. If the directory is your wordpress directory, you should see the directories wp-admin, wp-includes, wp-contents. If you do see that then you are looking in the right directory. See if favicon.ico is also there. If not, upload it again to that directory. If you DO see it there, then change its permissions to allow it to be read. (Exactly how you do this depends on which ftp software you use. If you are using a unix or mac based ftp from command line, you want chmod 644 favicon.ico)

In sum, it was not actually a problem with the plugin. Unfortunately, I do not know if he was able to resolve this. It’s been about a month since this exchange of emails and I just checked his site, no favicon. Then again, he hasn’t posted to it since then either, so perhaps he’s on vacation.

But imagine if the original message had been something like this:

Hi, I’ve installed the favicon wordpress plugin at my site [correct url} but I can’t seem to get it to show any favicon in the browser location bar or in the tabs.

I’m on Windows XP, using Firefox (latest), my WordPress (version 2.0.3) is hosted here [description], installed by default in the top directory.

I unpacked everything into the plugins directory according to your instructions, turned the plugin on from the admin panel, and went to the Options/Favicon page. I entered the location of the favicon, and clicked on update options. But no favicon appears. It should be at http:/mywordpressblog.com/mywordpress/favicon.gif

Thanks!

At this point, I’d probably reply

Hi! I tried the address for the favicon you gave me, but it gives me a 404 error. This means that the file itself is either not there, or it does not have the permissions necessary for me to look at it. [Repeat of last message above.]

Notice the time saved, too. Instead of several days (as the actual exchange took) the reply can deal with the solution almost immediately.

Let’s suppose hypothetically that the person used IE6. And I went, hmmm, tried it with IE6 and realized there was a blankety blank bug with the layout or something that meant the favicon name was not correctly recorded. That’s why something that might seem irrelevant (what did Firefox have to do with this problem, after all) could actually be. Any time several applications intersect, it’s possible for one of the other applications to be the actual problem.

Here’s another point. Let’s say in the hypothetical example above, the user includes a snapshot of the page he gets after clicking on the submit in the favicon admin panel. I might look at that and say to myself: “Self, you’ve got to add a better error message if the thing can’t be displayed.”

And in fact, I should run off and do that, and put out an upgrade to the plugin…

In summary

So let’s recap:

• Computer: operating system, version
• All involved applications (programs), versions
• Exact sequence of steps taken to reach the problem
• Meticulous description of problem (missing information, wrong information, layout, can’t see, I expected A and saw B)
• Any and all actual error messages (and quote them exactly instead of paraphrasing)
• Any other information that might be relevant (first time this was tried, it worked yesterday, it doesn’t work since I started using this version of the application)
• General description of intended activity (believe it or not, sometimes I get completely sidetracked on something different because I was not aware of what the user was actually trying to do)

The description of the problem must be as complete as possible. Treat me like an idiot and describe everything. What did you click on, what did you do, what did you see? What, exactly, would I have to do to see the same problem you saw?

And remember. Maybe coming up with a comprehensive bug report seems like a lot of work. But trust me, it’s plenty of work on my end to fix it. The more information I have to work with, the less time I spend trying to figure out what the actual problem is (which the user knows but I do not) and more time on fixing the problem (which I know but the user does not).