I’ve written bug reports in the past that suck… No that REALLY suck.

From spares one liners to the long epics. I’ve done it all.

Thankfully now I know better.

But back in the day, how did I know?

Well it was my first gig after college, I was working customer support for a small startup.

Whenever I escalated a customer issue to development team they could rarely reproduce it.

They might have came back to my desk 20 times to get more information, or worse after looking into it they found that it wasn’t even a bug to start with. Yikes!

Writing bad bug reports is a productivity killer.

So I did what anyone would do when they’re drowning… I learned how to swim.

Key Components Of A Bug Report

• A title.
• Severity & Priority.
• Environment where this is happening.
• Quick summary of what’s going on.
• Clear reproduction steps.
• What you expect to happens.
• What’s really happening.

Those are pretty much the basics that every bug tracking / product management tool will support.

What Makes A Bug Report Not Suck

A.] Cut The Fat

Only add the minimal effective dose. You don’t want to be the person pulling a filibuster in your bug report. Keep it short and to the point.

B.] Explain It Like I’m 5

Reproduction steps should be so clear that even a 5 year old or new team member could reproduce the bug. Don’t worry 5 year olds are pretty smart.

C.] Give It To Them Straight

Reports should use simple language. This is not the time for literary prose or haiku.

D.] Search Friendly Title

This will help avoid duplicate issue reporting. This gets more important as the team starts to grow.

E.] No Double Dipping

Keep each bug report related to the same area.