(Русский перевод этой статьи)

You go to the kitchen and turn on the light to see what's so nice. Has your darling husband been cooking for you? However, something's broken, and the light won't turn on. How are you going to tell him that?

«Sweetheart, please replace the bubble in the kitchen» or «Darling, it's dark there»? At this very moment, your darling is having a hard time with SVN trying to merge two repositories, and he couldn't care less for your light bulb.

So how do you tell him? You can’t just shout out the words in the air. How do you tell him so that he will listen to you and understand the problem?

This is called a «bugreport,» a description of something that has gone wrong. This came from the software industry, but generally, it has something to do with us humans and how we talk to each other. Not that it really matters, but it's good to know how to report problems and issues to colleagues and friends, not just report, but because we also want our mates to get the message clearly. We want them to start looking for the solution immediately, even if that happens at the back of their mind.

No matter how blondish the bugreport is («This thing is kinda, like, broken»), you will still have to reduce it to something clear. If the original bugreport is fuzzy, you will spend time asking stupid questions («Which thing? Why is it broken?») and will end up with stress («I've told you already, it's not working!!!»).

Programmers used to think things clearly (okay, I'm trying to be positive). During years of growth in the IT industry, they have invented a nice and simple way to describe bugs.

Priceless bugreport

The priceless bugreport has three important items:

What did you do?
(Steps required to reproduce the problem)

What did you get?
(Actual results)

What did you expect?
(Expected results)

Also, you've to tell where exactly the defect has been found and give the bug a short title.

“Dear, I have tried to turn on the light in the kitchen over the oven to see what have you cooked, but the light doesn’t turn on. Can you please take a look at what's wrong?”

What did you do? What actions have you taken to get this result? Explain step by step.

What did you get after you have executed all the steps mentioned above? This is the actual defect.

What did you expect? What you think must happen after the same steps are executed in the correct system.

Also:

Where did it happen? This info must be also present in the bugreport. The reader must have an immediate understanding of the scope of the problem, i.e. which part of the system could be affected. You don't have to write this down as an additional item. You just have to mention it. You may also tell this in the «What did I do» clause because travelling through the system to the buggy form could be considered actions as well.

Environment. This comprises of everything that is not an action but what is important to know. Say, for a web application, you must note the browser/OS combination.

Title. This is the shortest bug description possible. You will use it later in bugs lists, hallway discussions, etc.

This is a very nice form:

1. It's straightforward. The bugreporter can't really populate it with useless noise, unless he will try hard to ignore the rules.
2. Verifiable. It means that by reproducing the written steps of instruction, you will get the very same result and confirm that the bug truly exists. Or, you will end up with a different result so that you could fill another bugreport for another topic by yourself. Or, you will get the expected result and reject the bugreport.
3. Self-confirmed. You can immediately tell if that is a bug or not by looking at the «Expected results» clause. What if it's not a bug at all? What if there is no torch installed in the oven in the first place, and the light switch is an orphan piece of hardware mounted by the manufacturer simply because the Chinese engineer failed to merge two repositories?
4. This form eliminates the stressful stupid communication, those boring what-did-you-mean-by-that questions.
5. It's easy to teach regular people to report according to this form—only two or three days of crying and tears in your office, and your colleagues will learn to report things clearly.
6. By explicitly telling you what the expected results are, the user will confirm that he indeed knows what the system is supposed to do.
7. This kind of bugreport doesn't motivate you to skip on it and pretend it never existed.

Examples

A bug that was noticed by the user:

Can't login

What I did:

1. Opened http://www.something.com/
   
2. Clicked on "login", saw the login form
   
3. Entered "egor" in the login field and correct password in the password field, clicked on "enter" button
   

What I have got:
White page, URL in the address bar is http://www.something.com/checklogin

What I have expected:
1. Login form with "incorrect password" or
2. Main page of the member area

Environment:
MSIE 9.5b2/Windows7

A bug that was noticed by the system administrator:

Exim died

What I did:
Ran /etc/init.d/exim4 restart on server shovel.something.com

What I have got:
touch: `/var/lib/exim4′: directory not found

What I have expected:
exim restarted, standard success message on stdout

A bug that was noticed by a programmer:

dbPeerAccess->version() got broken

What I did:
use dbPeerAccessor;
use DBI;

my $dbh = DBI->connect("dbi:mysql:telme", "telme", "telme");
my $dbAccess = $dbPeerAccessor->new($dbh);

What I have got:
$dbAccess->version() == undef

What I have expected:
$dbAccess->version() == "1.3.0″;

Environment:
trust:htdocs egor$ mysql -utelme -ptelme telme
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 302
Server version: 5.0.51 Source distribution

Type ‘help;’ or ‘\h’ for help. Type ‘\c’ to clear the buffer.

mysql>


BTW, this kind of bugreports (on the code) you can report as a single piece of code (a test case), just like that:

use dbPeerAccessor;
use DBI;

my $dbh = DBI->connect("dbi:mysql:telme", "telme", "telme");
my $dbAccess = $dbPeerAccessor->new($dbh);
printf("dbPeerInstance is %s\n",
    defined $dbAccess->version() ? "defined" : "undefined");


A bug that was noticed by the project manager:

"Forgot password" must work in a different way

What I did:

1. Opened http://www.something.com/
   
2. Clicked into "forgot password"
   
3. I see a form with the email field
   
4. I typed in my email that is existent in the database and which belongs to my username
   
5. Clicked "submit"
   

What I have gotten:
1. "The new password has been emailed to you"
2. A letter came in which was the new password delivered in plain text
3. This new password indeed works, the old password doesn't let me in anymore

What I have expected:
According to our specs, the email must contain a link to the "generate new password" page and not the newly generated password.

A bug that was noticed by the CFO:

Why such expensive chairs?


In the report dated 01.04.2008, I can see the «Furniture» clause and the «Chairs for new programmers» item. Two pieces were bought at $1,400 each. Well, we assumed that Carl will order chairs priced no more than $200/piece for his department, and definitely not fourteen hundred bucks. Please argue such an expense. Please do not refer to the April 1st.

As you see, it's not required that the text must look exactly like the form. Is it important that all the information required by the form is there. The programmer's and CTO's bugs are perfect examples of how you can report the bug in different ways and still comply to the form.

No pain — no gain

There is one more thing that you have to be warned of before you establish this bugreport form (which is in fact a business process) in your team. You see, nobody wants to feel stupid; moreover, the person who discovered the bug will immediately feel that he’s smarter than the programmer who let this bug happen, even unintentionally. Thus, having discovered the bug, the user will feel absolutely comfortable filling a bugreport like “This piece of shit doesn't work, period.”

This is why enforcing this form in a team will be a painful step. The pain relief will come quickly in a software development team, because software developers tend to be highly rational people. This is not so in other industries. These kind of bugreports bring transparency to the working process, and transparency require additional effort, which nobody wants to put in. In addition, not all people can really understand what the context is anyway, and why his mate doesn't have a clue what's he talking about. See, the program just doesn't work, why don't you see it, look, it's so simple.

Once, I had to introduce this business process in a company where only a single manager was allowed to talk to the customers. She collected feedback and requests from users and filled up bugreports for the software team. As most of the nontechnical personnel, her mind process wasn't so straightforward like ours, the programmers. When the bugreport form was enforced, she cried, she screamed, she promised to kill me and all my people, she took cold showers, then she cried, she cried and cried. I was so sorry for her! She was in her tears and felt betrayed. Nonetheless, I was still heartless and rejected bugreports one after another until she learned this simple form. It took her three days to calm down. Two more days and she was comfortable submitting perfect bugreports. Two more days and she didn't turn back to her past practices. She became a wholehearted evangelist of this approach in the company. Her productivity increased considerably, and customers' issues were resolved more quickly from that moment on.

To conclude, I suggest you the following. Introduction of this bugreporting approach in the company must be enforced. It must be enforced by the team leader, and only when the team leader truly knows why he wants this approach and what its benefits are for the business.