Keep Your Technical Details to Yourself

I was looking at the error report from one of the front-line users at my employer, and they had included a screenshot of the system. The system was helpfully telling them:

An error occurred: java.lang.NullPointerException

It’s incredibly frustrating for me to see something like that. I appreciate that the system is trying to be helpful, but it is never ever a good idea to show internal details like exception names to end users (i.e.: non-technical users).

Why Not? It’s Useful Information

The error details are certainly useful… to developers and administrators. I’m sure I’ve written software myself in my younger days that helpfully explains to users the technical details of the error, including the exception classname or internal error code.


It wasn’t until I started working in Operations and directly supporting end users that I realised the psychological effects that this kind of information can have on end users and the significant costs that result.

Essentially, many users see error messages with technical detail and interpret that as the system has failed in ways those techo guys didn’t expect and so this thing must be pretty crappy and unreliable. Confidence in the system is easy to destroy and hard to rebuild.

Is that important? For paying-customer software the answer is obviously yes – confidence in the system is directly proportional to revenue. What about for internal corporate software? After all, the users don’t have any choice but to use the application, so it doesn’t matter if they like it or not.

There is still a significant cost in corporate environments: the change management cost. When users have no confidence in the platform:

  • Communications strategies for future changes become more costly and less effective because disillusioned users aren’t listening.
  • Engagement for requirements and design for future versions becomes more difficult (“I don’t have time for this requirements meeting, I’ve got a job to do and the system is crap anyway.”)
  • Supporting the software becomes more expensive, as users are quicker to jump to support, and less helpful when engaging the support staff.

All of these costs are hard to quantify, which means they don’t end up explicitly in project plans and support models. That’s why we end up with these kinds of errors being displayed in dialogs to users, and nobody really caring about it.

What should developers be doing instead? What if you can’t prevent it?

Firstly: developers should absolutely create systems that record as much detail as possible, and make that data easily accessible to support staff with the relevant customer/user details. Specifically:

  • Log everything together in a central place, but make a special “support staff” view (accessible with elevated rights) where support staff can quickly query the error information from the live system. I’ve seen too many systems where the support staff need to raise a production service request on another support team to get an extract of the logs, which leads to user conversations like, “I’ve logged a support ticket for the error you’ve reported, I’ll get back to you in a couple of days.”
  • Don’t expect the support staff to wade through a stack trace to find the source of the error – summarise your best guess of what have might have occurred (e.g.: error communicating with XYZ service”) so that the support staff can quickly triage the issue and start taking action. It’s often not possible at development time to know exactly what may have gone wrong when the code executed, but there is always some interpretation possible. Even a list of possible reasons for the error is helpful for support staff.
  • Log all of the relevant details together so that support staff can query based on the information they know. The end user will report an error with something like a customer ID, case ID or transaction ID, so the support staff need to be able to query directly on that business-domain parameter. I’ve worked with systems where the support staff have to query on internal database IDs or date ranges and then hunt for their data across multiple database tables, and that obviously leads to poor customer experience.

So that leaves the question of what to put on screen, and that needs to be answered with, “what can I put on screen that maintains or builds user confidence?”

Technical information that is meaningless to the user does not build confidence. Confidence is built when the system appears to the user to have the issue under control, which means a business-language message about what occurred, and a clear statement about next actions – and often that is simply “try again”. It’s important not to leave any ambiguity in the users mind about whether their data is safe or corrupt, if the system will recover, and what their next action should be.

The message I saw at work was

An error occurred: java.lang.NullPointerException

A much better message would have been:

The Credit Decision service did not respond in time with a decision about the credit requirements for this customer.

Wait a moment and resubmit this application for credit decisioning, as the service may be experiencing high demand. If the problem persists contact the XYZ Support team and quote your application number.

The downside of providing better error messages is that they tend to be longer, and users are infamous for not reading anything on screen. This is exacerbated by a lack of confidence in the system – they’re even less likely to read longer dialogs when they have no confidence in the system’s robustness. Still, it’s better to have the information there than leave the users wondering if the system has eaten their data.

So what about when it’s not possible to prevent technical information from appearing in front of the users? Not possible implies something that can’t be predicted and from which the system can’t recover on the fly (if it could recover it could deliver a controlled error message). If the system is in such a catastrophic situation then it’s pretty reasonable that technical information might end up in front of users – hopefully these kinds of situations are pretty rare for your organisation, and if they’re not, it’s probably worth tackling that instability first.

I Shall Not Kiss Babies

In the unlikely event that I run for some sort of government office, I hereby do solemnly swear that I will not kiss any babies.

I really don’t understand the motivation behind it. It would be creepy and weird if some bloke came and kissed my kids on the head, why would you do it to a stranger’s kids?

(I’m not a kiss-to-greet person in general anyway – polite handshakes and nods all the way for me.)

Conference Lines

I have spent too much time at work exchanging confused looks with colleagues while we try and figure out what the guy on the other end of the conference line just said.

If you are that person sitting on the conference line typing away at your emails on your noisy keyboard without your phone on mute: I hate you.

I Misspoke

Well, that was embarrassing.

I was just talking to a work colleague, and we agreed to meet next week to catch up. So I tried to say to her, “Great, I’ll book a 1/2 hour slot in your calendar early next week.” Did I manage to say that? No.

“Great, I’ll book an hour in your slot then.”

The Promise of SharePoint

Too often at work I send an email that says:

“Latest version of <Some Document> is attached, and I’ve also uploaded it to the SharePoint.”

Every time I hit send, I imagine someone on the SharePoint team dies a little inside.

(For the record, I’ve tried not attaching it and just putting the direct SharePoint link in the email, and every time I get a bunch of replies, “please send me the latest copy.”)

Scorpions: Wind of Change

This song convinced me to buy my first stereo system. I remember standing in the [Big W] at Karrinyup shops, and this song came on a TEAC stereo system sitting on the shelf. It sounded better than anything I’d heard before (all we had at home were mono-speaker radios and TVs) and I was convinced to buy it right then on the spot. Still think about that moment from 1991 every damn time this song comes on the radio.


I had surgery under general anaesthetic today, from a surgeon I’ve only briefly met in his consulting rooms. In the last few moments before I went under, my conversation with the surgeon was like this:

Surgeon: So you’re a police officer, right?

Me: No, I work for a bank.

Surgeon: Oh right, but I know your in-laws, right?

Me: No.

My last thought before going under was, “Wait, am I in the right place? What is this guy going to do to me?”

Thankfully when I woke up it was all okay, and I have a lovely new pair of boobs.