On writing bug reports that make your developer happy

In working with clients who are not developers or who have never really been deep in a software development process, I find that time and time again the communication always seems to break down when it comes to reporting issues (or ‘bugs’). Every development project seems to have them (I don’t care how many unit tests, functional test or testing and QA plans you have there will be bugs) I have taken great liberty to borrow some great ideas in this regard from Brent Simmons (of Ranchero, UserLand, NetNewsWire, Newsgator, Glassboard fame) he wrote are really great piece How to manipulate me (or, Tuesday Whipper-Snapping) about feature requests and bug reporting, really if you have the time read it instead of this piece it is worth it. I’m going to focus on writing helpful bug reports here.

In a client development project there is nothing more valuable then time. Many client projects are billed by time, anytime spent working on a bug means you are not working on moving the project forward.

Time is so precious, it’s everything

Here is the part that Brent articulates so well

What’s the hardest thing about a bug report? Almost never is it actually fixing the bug that’s hard. (Sometimes, but not usually.) The hard part is reproducing the bug—that is, understanding what’s going on and being able to make it happen at will.

Once I understand a bug and can make it happen, I can fix it.

The reproduction of the bug by the developer is almost always the hardest step, it can take seemingly forever (read this as many many dollar signs) if the description of the bug is vague or tangental to the actions the person was taking at the time. Brent has three questions that I have built into every bug reporting form in every app I have built since I read this piece, in web apps, desktop apps, iOS apps. Heck I even follow this when I talk to the mechanic for my old car.

Give me the steps to make the problem happen every time (or even most of the time) and I will fix it quickly, if I can see it in the debugger (I know a geeky term that I am not going to delve into here ;) that is even better. Not only can I usually see the very line and conditions with a great level of detail and track down the issue, but I can know that it is fixed because I can follow the steps and it is gone.

So here are the questions to make sure your reports follow to your developers. These are Brent’s!

  1. “What I did?”
  2. “What I expected to have happen.”
  3. “What actually happened.”

“What I did?”

The most time consuming part of almost every bug is REPRODUCING IT it is almost never fixing it. It can literally take hours to reproduce a poorly articulated problem and just a couple of minutes to fix it. Saving me time saves you money and lets us make progress on the project moving. Just give me the steps, don’t try to figure out what is happening, or why you think it is doing what it is doing, that is my job we don’t need you to spend your time on that.

The other thing is there is a delay every time we have to go back and forth on the steps to reproduce it. Every email is going to have a delay, make the first one count.

“What I expected to have happen.”

So many bugs are really ones where there is a mismatch between what the user expects to see and what the developer built it to do. We are the visitors in this project we are working to map a workflow or a vision that you have a deep intuitive knowledge of and a set of expectations on how that would map for you into a touch based interface that is less then 10 inches diagonally. We on the other hand have a lot of experience with how iOS apps have traditionally behaved and how interactions will lead to certain outcomes. It is expected that these two views of the project will differ and working through those perceptions take clear expressions of expected behavior. Many times what you see is a bug is really us misinterpreting what you were thinking, and this is the perfect time to clearly state what you think should happen. These may be areas that are unclear in the “Book” or something in the interaction design that is just not quite right.

Not always sometimes it really is a BUG, it is also important to report regressions early these are almost always things that are a lot easier to fix the earlier they are reported. (A regression is something like “last time it did x, now it does y”)

“What actually happened”

This is related to both of the above points but the biggest is if we don’t know clearly what you are seeing we will not know that we are recreating it, and then can begin to fix it. Screen shots can help but a good description can most often be enough.

Joel Spolsky also echoes a lot of this in his piece.

One issue at a time

Now related to this is another point that might strike some people not in the software development business as strange and wasteful (there are some other terms that people have used to describe this that I am not going to share, that is for another time) This is the idea of One issue per report I know it seems wasteful and time consuming but it really makes a difference. It keeps the conversation that might take place focused. It helps things from getting lost. A long list of bugs or issues that then leads to a protracted back and forth game of twenty questions can so easily lead to one or more of the items in the original email getting lost in the shuffle. Also on the back end we are going to put these issues into a bug tracking system that doesn’t let us forget things, that lets us prioritize and associate issues.

To be perfectly honest it keeps us happy, it feels quite good when you can check off an issue report as DONE. You may not know it but these issues keep us up at night, they are what we think about while we are riding our bike, they are what ‘distract us’ in normal day to day life. Plus we may not be able to address all the ‘issues’ in a multi-issue email in the ‘next build’ It helps us to report progress and doesn’t make the project feel ‘stuck’

Another restart…

I am not sure what the new start on this blog will result in… I am hoping to post more photos, and to perhaps share more about what is going on in the family and around Tucson. I am still struggling with the lack of value that my state puts on education and the long term impact that will have on my kids and the region that I have grown to love. With the 1% sales tax for education about to expire and the proposition to extend it indefinitely tied up in the courts I do hope that the http://100StandsForEducation.com can come back to life if it ever comes to the ballot. Cross your fingers.

Vote Yes On Prop 100 | Feature | Tucson Weekly

Vote Yes On Prop 100 | Feature | Tucson Weekly

If the sales tax does not pass, lawmakers won’t look for a more equitable tax. Instead, they’ll take it as a mandate that voters want more cuts%u2014and they will proceed accordingly.
We already know what they will cut if the sales tax does not pass. They will cut another $428 million from education. They will cut $107 million from our universities. They will cut about $150 million from health-care funding. They will cut $100 million from the criminal-justice system. And the list goes on.
Those cuts will mean the state will lose another 13,000 jobs, according to economists at the UA Eller College of Management. On top of that, we’ll lose more than $442 million in federal matching funds that would bring new dollars into our economy.

Take the time, talk to your friends, our kids can not afford this, we can not afford this, our state’s long term prospects can not afford this

 

But we don’t have those choices. Instead, we have lawmakers who can’t wait to cut even more as soon as you give them an excuse. They’re the ones who are telling you to vote against the sales tax so they can get on with the slicing and dicing of everything that Arizona taxpayers have built over the last 100 years.

If the sales tax fails, the people who want to destroy our state win.

Save the state of Arizona. Vote yes on May 18.?

 

100 Stands For Arizona | When life gives you lemons, make lemonade.

100 Stands For Arizona | When life gives you lemons, make lemonade.

100 Stands for Education

When life gives you lemons, make lemonade!

Stand with other Arizona children and parents to raise awareness of the crisis in K-12 education and to support Proposition 100. On May 8, 2010, be one of the 100 Stands for Education selling lemonade to support Arizona public education and to spread the message: YES on 100.

This family-friendly program benefits local schools and gets the word out on the importance of Prop 100 to public education. All lemonade sale proceeds are donated to the local public school of your choice.

Voigtländer Keepsake

Voigtländer Keepsake Originally uploaded by sdevore

Voigtländer Keepsake

I have so many slides from my grandfather taken from this camera, the sad part is I would love to get it working again, but no camera shop I can find will even try to repair it… I do just the heft of the camera, and how it feels so solid and the smell of the leather is just so transporting back in time…