Nobody likes error messages – but the misery is compounded when the messaging doesn’t even point to the problem. In this lightning talk filmed at DevRelCon London 2017, Atsushi Nakatsugawa advocates for a better way. A way that developers will understand. A way that, most importantly, won’t have them reaching for competitor offerings.
Thank you. Thank you for coming. I’ll talk about the DX of error messages and this is a very short version. I have just five minutes so first, I’ll introduce myself. I’m Atsushi CEO at MOONGIFT and I’m the organiser of DevRelCon Tokyo 2017 and organiser of DevRel Meetup Tokyo, Singapore, Sydney, and Bangalore. So please raise your hand if you’re programmers. Okay. And do you write DevApp? No? I love DevApp so much.
Here’s an example story. I’m writing code every day and so maybe I use, now, Web API, so something external is the case. And I write, maybe I got errors like that but I don’t ever give up. I fix up my codes and run again. Maybe I’ve got errors, you know. So I get frustrated but I don’t ever give up and I’ll update again and run the code like that. So I hate everything and…do you like this ASCII art? It’s like an old Japanese, low table and I hate everything and I quit the job and I go to vacations and yeah. But we have to write the code again. And just…I want to introduce to you the worst example. I don’t say what type of services but this hub has very worst message. Their error message, everything right down to an “Oops, error occurred.” It’s a very bad message for us so if you use services return very poor messages, maybe your developers are chained to competitor services, maybe. But if you return to a better error message and you can support your developers by error messages, they love your service so much more, they like your service.
So I think the best error message is one the developer can understand, what should they do to the service. So, this is an example. This is a very poor error message and the change looks like that. Return to a code and messages, so we should update it more so it looks like that. What is wrong? So, before there is “missing required parameters,” but the next is “name and email parameter are required.” So your developers can understand we have to input name and emails. On the contrary, some APIs return the documentation URLs so it looks like that so your developers go to their documentations and they can understand how to resolve their problems.
And this is a good example by Square. They provide to you payment APIs and you can see the red strings, “line items, zero name” so I can understand my problem. Maybe line items is arrays and the first arrays name is required. And the next example is a Google Maps. If I use Google Maps API without API keys, their error message looks like that so we…I go to Google Maps and get the API keys and then I can use Google Maps APIs.
So, in summary, it is an opportunity to increase their loyalty if you provide the best error message and I think the best error message is indicating next step to developers. And the rest…this is the rest. We provide to DevRelCon Tokyo 2018, maybe July 14th or 15th, so please save the date. Thank you.
Jamie Wittenberg from Major League Hacking discusses the various ways in which your documentation can lose new developers in this talk from DevRelCon San Francisco 2019.
Write for us