It’s easy to assume that someone needing user support is not using the application correctly. What if there really is a bug?
We’ve all seen the acronyms from user support techs: ID-10-T errors, PICNIC, PEBKAC, and so on.
On the one hand, they’re pretty mean-spirited (but kinda funny). On the other hand, who can blame user support techs for being exasperated when rude, frustrated users scream at them to solve problems that aren’t their fault. Yes, some support techs really do have to walk users through the most basic of operations. REALLY basic, like making sure the computer and monitor are plugged in and powered on. On the OTHER other hand, it is the job of support techs to bridge that knowledge gap.
As consultants, we are often called upon to support our own or someone else’s software. We have to be the opposite of that acronymic stereotype. Users aren’t idiots; they’re experts in something we are not proficient in and vice versa.
Once in a while, we are on the receiving end of user support, and these experiences can be real eye-openers. I remember one instance where we found an undocumented limitation of a mature third-party application.
I’ve followed the instructions. It still doesn’t work.
Don’t get me wrong; the support techs were good people. They were not rude or patronizing. They were just so sure that the right combination of settings would solve the problem. After all, this product had been in international release for a couple of years. Isn’t it fun to be an edge case? (Nope.)
Documenting someone else’s bug takes even more rigor than documenting one’s own. In the case of well-established software, bugs are assumed innocent until proven guilty beyond a shadow of a doubt.
Found a bug? Document, document, document!
Start with the most basic information:
- What environment is running the software?
- Hardware details
- Operating system version
- What system privileges does the running user have? (Some applications require that the running user have at least local administrative privileges.)
- Where are the application and data files housed, and what access does the running user have to those file locations?
- What version of the software are you running? Are you sure it’s the latest version?
- The vendor may already have found your bug and resolved it in a later release.
- What other elements of your particular computer and network could affect the software’s operation?
- Security software
- Firewall
- Network limitations or throttling by the connectivity provider
How can user support techs reproduce the bug?
Once the you’ve fully defined the environment, move on to defining exactly how the buggy behavior arises.
- Start with how the application is opened.
- Does it start automatically on system boot?
- Do you open it interactively from either the Start menu or the task bar?
- Does another program open it automatically?
- Document every single keystroke and click!
- I’m not kidding. Every. Single. One.
- If the application receives input, include an input sample that causes the bug.
- It can help to include more than one sample, if possible.
- Include ‘good’ sample input for comparison, if possible.
- Show what happens when the bug arises, whatever that may be:
- bad or inaccurate output
- error message
- crash behavior
- Take screenshots at every step.
- Better yet, use screencast software to record your actions and the application’s behavior in real time. There are plenty of free tools for this.
- Make this detailed log available when you reach out to tech support.
OK, it’s reproducible. Now what?
Now you have a full report of how, when, and where the problem happens. Deliver it to your user support contact and be prepared to answer questions.
It can take a huge amount of time to convince a software vendor that the bug you’ve found is real. Providing the user support techs with full documentation speeds up the process. It helps them rule out user error or misconfiguration.
In our case, we worked with several people at higher and higher levels to determine that the software does not support our particular use case. The vendor couldn’t even promise to support it in the future. As a result, the vendor updated its documentation, and we were able to move on and develop a work-around within the overall solution.
TL;DR
Sometimes a support issue really is a bug. If you think you’ve found a bug or an unsupported use case, documenting it rigorously will save a lot of time, both for you and for your support contact.
Have you ever had to report or verify a bug? Let’s compare notes in the Comments below.
Questions? Contact us here.