Results tagged “Writing” from estevenjones.com

No matter what you are using to keep track of defects that you find in your software, there are certain things that you should keep in mind when you are documenting a defect.

1. A CLEAR AND CONCISE SUBJECT LINE / TITLE
   This might be the most important part of creating a good defect report.  With this, the people responsible for fixing the bug/defect and quickly group several similar or identical problems into one investigation.  A good description will have at least 2 elements:  An action taken and a result
   
   EXAMPLES:
   Bad:  The website isn't working.
   Good: Clicking on 'Home' link takes me to a "missing page" error page
   
   
2. CLEAR AND CONCISE STEPS TO REPRODUCE THE ISSUE
   More often than not, a majority of the time it takes to fix a defect or bug occurs in the "trying to reproduce it" phase.  Even if we track you down to have you give us a demo of the problem and that demo only takes 2 minutes, the time it takes to actually catch up with you and get that 2 minute demo stacks up quickly.  So, in the body of your defect, you should give developers more information than you think they could ever use.
   
   EXAMPLES: (We'll continue with the bug started in step 1)
   Bad:  I clicked home and was taken to a blank page.
   Good:
   1. I opened up a browser and navigated to our live site ( http://www.ourdomain.com )
   2. I logged into the site using the "Login" link
   3. I clicked on the "Message Boards" Link
   4. From Message Boards, I opened up the article "Summertime fun spots"
   5. I clicked on the "Add Comment" button
   6. I typed in a comment, but didn't hit [submit]
   7. I clicked on the "Home" button in the menu bar of the site
   8. I saw a blank page that stated the page was not found
   9. In the address bar, there was this URL:  http://joedeveolper.dev.ourdomain.com/home.html
   10. I'm using Firefox for my browser on Windows 7.
3. A RECORD OF REPRODUCTIONS
   There is an old and sometimes joked about adage that states "It's not a problem if was can't reproduce it." While this may seem rather flippant and careless, there's also a huge grain of truth in it.  Sure there may have be an actual problem, but in the terms of prioritization, I'm sure it's easy to see that a defect that is either un-reproducible or difficult to reproduce is less important to fix than something that happens all the time.  Of course, this is an over-simplification as a bug that wipes out all of your data, even if it is almost impossible to reproduce is pretty damn important.
   
   EXAMPLES:
   Bad: I think I heard someone else had this problem
   Good: I was able to reproduce this on Internet Explorer, too.
   Best: I was able to reproduce this on Internet Explorer too.  I also got Sally and Jim to reproduce it on their computers, as well
   
4. SCREENSHOTS OF THE PROBLEM
   If the problem is visual in nature, it's always a good thing to include a screen capture of the problem.
   
   EXAMPLE:
   "The background color for the Name and Description columns do not match on the albums listing page."
   
   
5. ADVANCED TECHNIQUES: Recording a macro to reproduce the problem automatically
   There are many tools out there that will allow you to record all the clicks and typing you do on your computer.  Recording these actions could prove to be very helpful to the people trying to fix your defect.  Even if you list all of your steps as accurately as you believe is possible, there might be something that you do, thinking it's insignificant, that the developer will catch on and realize exactly what the problem is.  Perhaps you clicked on the graphic of a button rather than its, text.  Perhaps you submitted a form by hitting the [Enter] key on your computer rather than clicking the [submit] button on the web page.  Another major benefit of recording your actions is that your recorded actions are now documented, and it might be possible to create an automated test from them.  With an automated test, your defect might be caught next time before it ever gets to a production environment.  Keep in mind, these tools record your actions ( move mouse here, click here, type this ).  It does not record a video of what you see.
   
   SUGGESTED SOFTWARE:
   
   Bad Boy a very nicely done tool that is, unfortunately, a windows and Internet Explorer only tool.
   
   Selenium IDE:  This tool is also a very good program.  It sits on your system as a Firefox Plugin.  So initial recording of a defect will be done in Firefox only, but it can be played back using several different browsers.
   

These techniques and suggestions are not the be all and end all of 'best practices' for reporting a bug or defect, but they will certainly get you further down the road in being a productive partner when it comes to making sure your company produces the highest quality software.

An Attempt At the Completely Absurd:

The glumblefilch sauntered into the room.  He was full of vim, vigor, and veracity.  His three blandlybulches protruded from his torso, nearly touching the floor and he admired them.  They were long and elegant.  Fragile looking but he knew they were sturdy.  The purplish hue they emanated set off the radiance of his six yellow eyes.  Most glumblefilches only had five eyes, but he had six.  He was quite proud of that, even if the other glumblefilches looked at him askance for his audacity, he had just one more eye that he could roll at their ignorance.

This glumblefilch was named Snodgrass.  That was not something he was particularly proud of, but it was his name.  He bore it with resolution and aplomb. He honestly didn't care what the other glumblefilches said about it.  It was better than Steve, Victor, and Roger. And it was miles above Roderick.  Roderick only had 3 eyes, Snodgrass mused, shaking slightly in his mirth.  A low chuckle escaped his lips.  Normally that would be fine, but tonight Snodgrass was with his boy at dinner, and a glumblefilch's low chuckle was actually quite a rumble.  His boy gave him a warning glance over his shoulder and Snodgrass settled down.  He didn't want to get his boy in trouble again. Last time that happened, Snodgrass wasn't allowed to come out from under the bed for a whole week.  That was torture.  Glumblefilches aren't known for there ability to handle solitude.  They need constant attention and reassurances or else they disappear.  By the time the week was over and his boy again came looking for him, Snodgrass had faded to near invisibility.  A couple hours later though, fueled by the laughter of his boy and the games they played together, Snodgrass was back to his three limbed, six eyed purpley self. 

The boy's mother had stuck her head into the room looking about curiously. "Who were you talking to?" she asked, her half smile showing she wanted to share in the fun.

"Just Snodgrass,"  the boy had answered.  With a confused look, the mother left the room.

So ... not wanting a repeat of a week under the bed, Snodgrass promised to be good during dinner.  He floated down to the floor folding his blandlybulches beneath him. 

He tried.  He really did.  He wanted to sit and wait quietly, but he was just not good at that.  After a few moments, he couldn't take it anymore.  He had to do something.  So, Snodgrass pulled himself into the tightest ball he could and rolled under the boy's chair.  Giggling softly to himself (this was going to be hilarious), the glumblefilch gulped and swallowed three big mouthfuls of air. Then he waited..   He could feel the air wanting to escape.  He held it in... He held it in more..  He giggled... Then he couldn't hold it anymore.

Remember when we talked about the rumbling of a glumblefilch's low chuckle?  Well, imagine what a full fledged belch would be like.  The silverware on the table rattled.  A Glass fell over, spilling milk onto the table.  The curtains flapped in the breeze.  The boy's mother fell over in a dead feint (OK, well almost).  The boy's father had the look of horrified disgust.  The dog ran into the living room, looking for a reprieve.  Low flying aircraft swerved crazily, looking for where that clap of thunder came from.

When the echoes died away, when the mouths of both parents closed, trying to hide their disbelief and the glumblefilch under the boy's chair fairly split in two trying to contain his mirth, the boy glared under his chair.

"SAMUEL!!!" the boy's mother admonished.

The boy looked astonished, "It wasn't me, Mom!!  It was Snodgrass!"

Samuel's father looked at him angrily.  "Young man, that is not the way we behave at the table.  And I've told you before.  There is no Snodgrass.  There is no such thing as a glumblefilch!!"

Snodgrass hmmphed quietly to himself. "No such thing??" he thought, "What does he know?"  In a rage, he rolled out from under the chair, hovered up to the height of the table and stretched out his blandlyfilches to their full reach. 

That's when he noticed he wasn't there.