Errors from dummies

One of the keynote that my manager took from a clients tour in the US, jumped to my eyes: “100% of the users want to take actions in order to solve problems with the product. They are mad at us for giving them poor general error messages”. He followed his sentence by “they don’t know what to do after seeing a message ‘two ways communication failure’ or ‘unable to retrieve results for X'”. I took a pause and thought about this request and really started to think about how can we write better errors for our clients – errors that will ENABLE the users to solve bugs on their own!

After spending about 2 hours throwing ideas on my white board at the office, I came to the simple conclusion that its…. completely feasible!

Softwares contain bugs in it. You can hire the best programmers, the greatest QA guys, automate your testing, you name it. At the end of the day, your release will contain (more than one or two)bugs. So the problem is that the users can NOT do anything in order to solve those code-related bugs, right? Well, I really hope so because I really like my job. but how can we, the developers, give the user helpful error messages that will guide him to solve the bug that just happened or at least make him feel like one of the R&D team?

I decided to split the bugs into two categories:

• Bugs that are solely code related: I’m sorry, but unless the user will have access to my source, he won’t be able to make the fix. Now, who the hack wants to give the users access to their code? No matter what you show to the user, you know that he can’t help you solving the problem right now. I believe that you can make him feel like he’s helping solving the problem right now. here is my solution for that scenario:
  
  
  
  • Show the user a simple “We sorry but it seems that an error occurred in our engine. We managed to log the error and our best guys are working on it! BUT, we need your help in order to make this bug go away FAST, will you help us?”.
    
  • After this message, show a little “form” with the title “Want to help us fix this bug quicker?” that will contains the following fields:
    
    
    
    • A short description of the form – just a label – “Please help us reproduce the actions you did so we will be able to fix this bug as soon as possible. We know that you have little time, if any, so we did most of the job for you by. It won’t take more than 30 seconds starting now…”
      
    • Bug title (write the action the users tried to do as default – for example “Edit user’s account”).
      
    • How serious is this bug for you: a simple select-list from 1(it bothers me but it’s not that important) to 5(I can’t work!).
      
    • Bug description (leave it empty) – let the user know he can leave it blank.
      
    • How to reproduce this bug (here is the catch: you’ll need to record the user actions in order to be able to do this) – write all the steps that the user did before he saw this bug. Let him edit the text with the flow (maybe he could add some value). Now, it’s critical that you’ll supply a good record mechanism as the user don’t want to work for you. If filling this form will take more than half a minute, forget it, he won’t help you.
      
    • BIG button – “I’m done, send it away”.
    
    
  • The message will be sent to the system administrator if the network is local or to the support service if the network is connected to the Internet. Attached to the user’s message you can add your personal log info (that depends on the application architecture of course, if you have Internet application you can log everything on the server anyway).
    
  • IMPORTANT: If the user sends the bug “help” form, and the bug solved quicker because of a good “how to reproduce” by the user and it was important to many users of your software – reward him and notify about it to the rest of the community (of your software). We want to let our “QA users” the incentives they deserve. I believe that letting the user “make some action” in order to help fixing bugs is better than just showing him “an error occurred, please contact your system administrator for further details”. (btw – who came with that fucked up idea that the world adopted so quickly?!)
  
  
• Bugs that are configuration related or business related: Hey! we have a chance here to make our users dream come true! there is a good chance that they CAN fix the problem by their own two hands. If the error happened due to Foreign Key issues, for example – the user is trying to delete a record that is referenced by other records, tell him that he needs to delete “X, Y and Z” (give him links that those records) before deleting the current one and explain why(the user’s knows nothing about database or software “logic”). If it’s something the user forgot to do, meaning the business flow is incomplete, tell him what he needs to do NOW and direct him (supply links or automatically direct him the the current place\position). If the current session of the user was ended so you can not save his form, try to save the user’s time and save the form into the cache, let him log-in and then direct him to the previous page he was at and fill the page from the cache for him. Can you imagine how grateful he will be? If the user made a configuration mistake and gave bad data so now he can’t send e-mails or run some process – analyze what went bad and give him a proper message. Avoid general messages on those scenarios like “SMTP error…” or “unable to delete the row” just because he forgot to fill some not nullable field. What you are required to do is analyze the StackTrace of the exception and to match it with the recorded flow (as I mentioned in the previous category) and try to provide a really good action items for the users. Let me tell you this, users will appreciate your effort in giving them a full details about what went bad and how they can play a part of the software developers and make the software better.

Most importantly, don’t show developer errors to the user just so he could call you(or your service) and say “Hi, I’m a customer of yours and I’ve got a strange error ‘SqlException: bad syntax in line 291 near ;'” ;-).