Jump to page content

Bug of the moment 2007-08-16

Public service announcement

I am sure this has been said countless times before, but clearly it needs to be said yet again as the message is not getting across.

It still amazes me how many people have no concept of how to report problems with computer systems. I was making cosmetic changes to a site’s shopping cart this afternoon, only to discover that the cart does not work, and likely has not done for about six months. Aside from failing in Firefox (calling document.forms.submit() on a form called “forms”) it had been down in general following a domain name change. A POST operation to a hard-coded fully-qualified address containing the old domain name was not surviving a redirect to the new domain.

The site owner had reported what I can only assume was this problem ages ago, but not in a way that made any sense, and I was not able to spot anything broken on the site. Had he clarified that the problem was with a later step in the checkout process, I would have immediately noticed it and got it fixed. From what little I understood of the problem (and I couldn’t get any more out of him as I recall), it seemed specific to his computer and I shrugged it off. There have never been any other complaints, which puzzles me further.

He is by far not the only person who cannot comprehend simple problem reporting, and it’s starting to drive me mad. Elaboration, precision and clarity alone would make a world of difference. Think about how the person reading what you wrote would interpret it – does it make any sense? Would they have any idea what you were up to? At all?

There are three important steps in reporting a problem:

  1. What you were doing, and what steps you took to do it – otherwise, it’s anyone’s guess and we guess incorrectly
  2. What you expected to happen – this allows us to determine if you understand the system and how it works: maybe you’re just confused
  3. What really happened – in enough detail that we can understand the problem, and this includes any error messages displayed (this bit is really important)

A lot of people seem to consider error messsages to be irrelevant and nonsensical technobabble to be mocked, but that cannot be further than the truth: they often contain valuable information about the cause of the problem, which is why they appear in the first place. Even if we cannot understand your explanation of the problem, the error code alone may indicate exactly what’s gone wrong, or a Web search for it will throw up useful information.

Vague explanations like “cannot log in” are next to useless (since that could mean many things), but a message such as “Connection refused”, although a meaningless false friend to most, is far more informative. Error messages must be quoted verbatim, not paraphrased according to your erroneous interpretations. “Refused” in this context, for example, is not about authentication but simply that the remote computer wasn’t listening for connections. You may not know that, but we do, so just tell us what the computer says and we’ll understand. Even apparent double-dutch like “0x800CCC90” (an error code) can be thrown at a search engine for answers.

Any further information is also welcome. No-one needs your whole life story, but your operating system and, if applicable (i.e. for Web-based systems), the name and version of Web browser as well. Anything else you consider relevant is worth throwing in. For desktop software, it’s especially useful to note how long the problem has been occurring, and whether you did anything that might have triggered it. (Someone hadn’t noticed that menu item captions in gaim and Windows Explorer had all disappeared the exact time he’d changed his Windows colour scheme to one that would leave menu item captions invisible in these programs.)

Most if not everyone reading this “blog” will feel that I’m preaching to the choir, but spreading this message far and wide on other blogs should make us technical folk’s lives just that little bit easier. Even the odd few people who understand what we’re saying and take it to heart will be that number of fewer headaches later down the line.

As a reward for getting this far (cheaters must go back and read from the top): here’s something funny I discovered, from the venerable Color It! 3.0 art package. Color It! is the only image editor I have ever seen to draw correctly anti-aliased circles, and I continue to use it just to acquire these shapes.

I discovered a bizarre feature whereby you can drag tool palette buttons around at any time, but it doesn’t do what you’d expect:

Instead of rearranging the buttons, it simply replaces the existing button with the one you’re dragging, creating a duplicate button. I can’t find any obvious way to rearrange buttons, only a way to render the tool palette useless.

Posted 16th August 2007 – Comments and questions?