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!
- “What I did?”
- “What I expected to have happen.”
- “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’