notepadAs a recovering news junkie, I’d say I know a little about what makes for great journalism. Yes, the subject matter has to be timely and interesting, and sure, the writing should grab you and help you to feel your way through the complexities of the situation, but first and foremost, the writer needs to provide you with a basic context in which the described events take place. Even the most junior reporter on a small town paper, the guy stuck covering city council meetings and supermarket grand openings, knows how to structure his article in a way that provides all the necessary information up-front in a structured, partially-digested form that ensures comprehension on the part of the reader. Sure, the writing isn’t going to earn him a Pulitzer, but he understands that his audience will get his meaning if he sticks to the most basic rules of thumb for journalists, variously known as “The Five Ws”, “The Six Ws”, or “The Five Ws (and an H)”.

Users of information systems (beta testers especially) could benefit from a bit of self-imposed structure as well when it comes to reporting bugs. I’ve gotten emails with the subject line, “SITE DOESN’T WORK!!!” and a blank body from panicked users more than a few times, but even the messages that go into more detail often fail to provide the basic information needed to begin investigating the problem. Users could help the software support guys (and by extension, themselves) out immensely if they could put themselves in the role of cub reporter for just a moment and describe the problem as if it were a news event.

Who?
From the system’s perspective, you are your computing platform. That basically means the hardware and software your application runs on.

  • Hardware – computer make and model and basic specifications (CPU type, amount of RAM, etc.)
  • Operating system – type and version
  • Other supporting software - Java VM version for Java applications, browser type and version for browser-based applications, etc.

Your name and contact information would be helpful too because fixing a bug often requires getting clarification from the person who reported it. Also because you’re my user and, darn it, I like you.

Where?
It’s not super important for me to know that you’re sitting in a fourth floor office overlooking the river in downtown St. Paul. From the application’s perspective, geographic location is almost completely irrelevant. A network address however, in the form of a dotted quad or a domain name, is often very helpful if the application in question is networked and I need to start paging through gigabytes worth of log files.

When?
Give me the time and date that you observed the problem as precisely as possible, and please make sure to provide your time zone so that I can adjust appropriately when paging through logs.

What?
Here’s where you get to unleash the frustrated writer (and end-user) inside. Describe what behavior you’re seeing in the greatest possible detail. Leave no stone unturned.

  • When does it happen?
  • Is it consistent or intermittent?
  • How long does it last? Does it go away by itself or do you do something to fix it yourself?
  • How serious is it? Does it crash your system? Corrupt your data? Cause you to lose work? Is it only a minor annoyance?
  • How pissed off are you?

Think of me as your own personal Scooby gang. Anything can be a clue, so if something seems weird to you, don’t be afraid to mention it.

Why?
I don’t mean this in the existential sense, but because you’ve answered the previous four of the five Ws, some ideas might be starting to form as to what’s causing this behavior to happen. If you’ve got a theory, don’t be afraid to shout it out. It might not be right, but it could save your support guy a whole lot of time trying solutions that don’t work.

And if it is right, your support guy owes you a beer. That’s the rule.

How?
Answering the sixth question, the infamous non-W that messes up the otherwise perfect mnemonic, is the job of your tech support guy. He should carefully consider your bug report and apply his knowledge and experience toward its resolution in the most elegant and effective way. He should let you know when the problem has been solved or, if it couldn’t be solved,

Such is the theory anyway. I’ll caution you, though, that guys who do user support for a while tend to become a little, well, bitchy. Or cranky. Maybe even assholes. This leads to all manner of problems – starting with rude dismissal of support requests to end users who can’t stand dealing with IT. It’s all pretty unnecessary. Each party feels pushed around and degraded by the other for no reason when all that’s really required is a little more mutual understanding and detail about the problem and the process.

So to review… The next time you submit a bug report, try to provide as much information as possible including:

  • Who? – platform information plus your name and contact info
  • Where? – network location (IP address or domain name)
  • When? – exact date and time (including your time zone)
  • What? – a detailed description of the behavior
  • Why? – any theories you have about the cause