A couple of months ago I ran into an issue with a car I rented, that quite much resembled a regular situation in software.
After a short trip in rural England, I got back to the hotel, parked the car, got out and started walking towards the hotel. A few seconds later, before I reached the hotel entrance, the alarm went off. I unlocked the car and the alarm stopped. Then, I got into the car and checked if any indicator light was on. Nothing, everything looked OK; no open windows or trunk. I locked the car again, waited a few seconds and the alarm goes off again. I switched the engine on and off with no luck either, the alarm siren would keep going off a few seconds after I would lock the car.
This left me with one single question in mind; “What the fuck am I supposed to do now?”.
I decided to leave the car unlocked for a little bit to go back to the hotel and start looking for a possible cause. I looked up the internet for this car model and alarm system. A couple of manuals turned up — looked like there was a different manual for every new version of the model. I started reading both of those manuals, until I identified an alarm symbol I also spotted inside the car. Then I read the whole section about how the alarm system works, how and when it gets triggered, how to turn it off, reset it and what happens when you lock the car. The most useful information I could extract is that after locking the car with the remote, if any of the windows, doors or trunk is not wide shut, the alarm will be triggered within forty five seconds and that unlocking, starting and stopping the car also resets the alarm status.
I got back to the car, opened and closed the trunk, all doors and windows. Everything looked like it was already perfectly closed. I turned on the engine and then turned it off. Finally, I got out of the car, locked, waited for a minute and the alarm did not go off this time, after all.
I wondered, what was the problem after all. I did not know. I still do not. And that is a problem. Anything could have triggered the alarm. There were way too many steps to follow blindly. It would be much simpler, if the alarm had also an indication of its trigger (e.g. an indicator light for the left back door).
The same goes for software. No one cares that an “Internal Server Error” has occurred. This is pretty much non-information; the error state is obvious and there is no next step for anyone. If there is something your users can do to avoid this error, they should know, like for example how to change the input they provide the system. If there is nothing they can do, they should know if your team is aware of this issue, if they will follow up with them, or they should be provided of a way to get in touch with someone about this.
Mistakes will happen. Errors will arise. Alarms will go off. This is fine, as long as there is a clear path forward for at least someone. Otherwise, error states turn out to be unpleasant dead ends for everyone — and no-one wants to be in one.
Let your users know what goes wrong. Do not leave them in the dark. Pave the way for their success.
Did you enjoy this article? If yes, you should know that we pay attention to subjects like this when we build software with LOGIC, whether it is for our clients or our own homebrews.