How To Write An Issue Worth Solving

Nearly 200,000 issues were submitted by DoneDone customers in 2012, and, already, we’re on a pace to eclipse 300,000 issues submitted by the end of this year. With all those problems logged, it's DoneDone’s job to make sure they get resolved as quickly as possible.

We already do a lot. Last year, we launched a new interface that lets you filter and group issues across projects. Just a few weeks ago, we added due dates so bug fixers can stay on schedule. We offer release builds – a simple and powerful way to coordinate testing multiple issues at once. And, we’ve always stayed firm on the concept that every issue is assigned to only one person at a time to fix or test. This helps combat the dreaded bystander effect.

But, one thing DoneDone can’t help you do is write a good issue. And, this may be the largest deciding factor on how quickly someone can fix an issue.

So, how do you write a good issue? Here are four simple rules to follow. Your fixers will thank you for it.*

Rule #1: Provide exact steps to reproduce the issue.

As obvious as it may be to you, be emphatically clear about how to get to your problem. If you’re testing a website, who did you log in as? What exactly did you enter into a form? What buttons did you press? Better yet, use a screen-capturing tool like Jing to walk the assigned fixer through how you got to your bug.

Bullet lists are also a great way to get steps down in an easy-to-scan format. DoneDone follows standard Markdown conventions, so bullet lists are as simple as pre-pending your list item with an asterisk (e.g. * Now click the “Submit” button). If your issue only happens sporadically, and you can’t find a real pattern to the madness, let the fixer know it’s sporadic, and don’t suggest what you think the root cause might be unless you’re absolutely sure. A gut feeling about why something is happening might just lead the fixer down a long path to nowhere.

Rule #2: Spell out your environment and the tools you are using.

The vast majority of our customers work in the web industry, testing browser-based applications. It’s critical to provide information like your browser and version, your operating system, your mobile device, or any other tools you’re using to test the issue. Ask any web developer how many times they’ve had to ask “Which browser are you using?” and they’ll get the shivers.

Rule #3: Explain what you see.

Yes, this may sound obvious. But, in the rush of the moment, you might get in the habit of starting out your issue description with "I get an error when...". What is the error? Screenshot what you see, or paste the error message that you get. A DNS issue, infinite redirect loop, missing file, unsupported file type, expired SSL certificate, authentication issue, internal server error, and a faulty internet connection are all errors that might have similar looking messaging to the average user, but they mean a world of different things to a fixer.

Rule #4: Explain what you expected to see.

Alas, while it might be obvious to describe the issue you are seeing, you can easily forget to explain what you think you should see. This is critical, not only so the fixer knows when they’ve got the issue solved, but also because it might unveil a misunderstanding in expectations that you two have about how something should work. Even if it’s obvious (“When I add 1 + 1, it should be 2.”), state it anyway. You just may discover your peer has been assuming binary arithmetic.

So, take the extra few minutes with each new issue you write. It might go a long way in helping squash bugs quicker and getting closer to being done (done).

* For more great tips on issue tracking, visit this classic Joel on Software blog post from 2000.