The key element to writing up bugs - Steps to Reproduce

I recently became painfully aware of a valuable lesson and wanted to share it with the rest of the community.

We had a particularly large deploy this time and we ended up having around 260 bugs + features, combined.  I'm the QA guy on the team, so once we deployed to the staging server, it was my job to go through each of those 260 work items and ensure that they were working as intended.  The level of information for each ranged somewhere between a few words and a nice, ordered bulleted list of exactly what to do.

Here are two ways of writing up Steps to Reproduce for a bug.

Here's how not to fill out the Steps to Reproduce section

Steps to Reproduce

The chart links are going to old urls

Here's what I'm thinking every time I open it:

• What chart links? We have charts all over the product.
• What were the old URLs?
• How do I know if we're going to the new URLs?
• "Hey, you guys!  Do any of you know what's going on here?  Oops, it's lunch time and nobody's here." 

As you can see, that has a very high cognitive load, is error-prone, and is a downright annoying way of QAing a product release.  I mean, you can't just go ahead and assume that it works.  Otherwise, they wouldn't need you to test it.  Now imagine going through this for each bug/product backlog item.  "Woo hoo!! One down, 259 more to go!  At this rate I'll be done in...6 weeks?!?!"

Here's a much better example

Steps to Reproduce

1. Open a report
2. Edit the content settings of a search
3. Click the "enable turbo speed" check box
4. Notice the dancing squirrel obscuring the save button
5. We don't like dancing squirrels in our product

Plus, most of mine have a lot of screenshots so that you could see exactly what it looked like for me.  Bug reports like that were nice.  I could breeze through those one after another.  Why?  The biggest reason is because of the low cognitive load.  I didn't have to think!  No, it's not a good idea to force someone to needlessly think.  My job is to make sure that the product doesn't break that way anymore--not figure out how you made it break and then make sure it doesn't break that way anymore.

Here's the Takeaway

The person who writes up the bugs or product backlog items is in a position to really show love or hate to their quality assurance personnel--as well as to the other developers who have to fix it.  Honestly, how much longer does it take to write a bulleted list of instructions on how to reproduce the issue?  I'd say that most would take less than two minutes.  I go crazy with mine and add screenshots even when I probably don't have to--and edit them in Microsoft Paint to highlight exactly what I'm referring to in the screenshot and it still takes me less than two minutes.

Let's compare two minutes up front to about 30 minutes or so each time I want to reproduce this thing.  

Rules of Thumb for filling out Steps to Reproduce

• Write it out in an ordered list of simple instructions
• Write it in easy-to-understand language.  The more explicit it is, the easier it is to follow the exact steps to reproduce the issue.
• If you come across a poorly-written or non-existent Steps to Reproduce, please do everyone a favor and fill it out

Oh, and be nice.  I didn't even think about bug report quality very much until I was in charge of testing.  I was the one who had to experience the pain.  I seriously doubt your teammates want to cause you pain.  It happens.  When they do, just send them a link to this article.

Keep on making this world a better place and may God bless you with grace and peace.

Hey, how about you take a few minutes and introduce yourself in the comments and tell us some of the things you've learned?  Come on--you know you want to!  We'd love to learn from you, too!

Brandon