00:00:04.940
I'm actually going to try and stay put this time because the last time when I spoke at this conference they gave me a
00:00:11.520
hand microphone and I kept walking over there but I had to adjust a spotlight and then I would walk back here and they
00:00:18.449
had to adjust it again and I did that a couple of times and then in the middle of the time there were like in the
00:00:23.760
middle of the talk they were like she's not gonna stop this she and then they just switched on the stage lights and no
00:00:29.670
idea what was happening I was like so I'm just gonna try and stay here alright
00:00:36.510
so as you might have guessed i'm laura i
00:00:42.560
i'm software engineer I work for a company in Tokyo right now we mostly put
00:00:48.329
ibeacons into vending machines and then do a lot of cool stuff with them and some more things but you can ask me
00:00:54.510
about that later if you want to and I'm going to talk about writing better
00:01:01.440
errors today what I'm not going to talk a bit about is how to craft the perfect
00:01:07.229
error message because I feel like there's already a lot of literature and like talks and stuff about that out
00:01:15.060
there but what I've always been missing is like kind of that step before like to figure out like what do you actually
00:01:21.600
want to say and to whom so I want to take a step back and talk about the
00:01:28.219
high-level perspective more about the approach how to become any tenure
00:01:36.189
I recently got a Roomba from a friend who's moving away from
00:01:41.259
Tokyo and and if you don't know what it is is kind of like a tiny little vacuum
00:01:48.250
cleaning robot which goes around on your floors including some so I got it and I
00:01:53.500
brought it home and then I wanted it to clean my floors so I put it on my floor and I pushed a big clean button and I
00:02:00.039
expected it to clean but it refused instead it started blinking at me and I
00:02:06.849
was like not quite sure what it's trying to tell me and because I'm a highly sophisticated
00:02:12.840
engineer I decided to approach this issue with a time-tested and proven this
00:02:21.099
practice method I push the random button to see what it does and it's all night
00:02:30.629
it's until fall you put up a steadily to be closer to
00:02:37.599
the microphone yeah okay I can do that right so I push this button and it
00:02:45.370
started speaking to me in Japanese I was like I can like I can speak some
00:02:51.220
Japanese it's not that great I was like mm and I push the button a couple more
00:02:58.720
times and I finally figured out it was kind of trying to say something about
00:03:04.389
era too so I deployed another time tested method which is googling the
00:03:10.690
error message and this is what I got era to open Roombas extractor frame and
00:03:17.079
clean extractors and eventually I figured out what actually wanted me to do is to clean the brushes and so this
00:03:25.030
is like most people nowadays don't really interact with robots everyday yet but what a lot of people do interact
00:03:33.370
with a lot is software on a daily basis and you kind of get the same stuff there
00:03:40.870
right this legend see this are like okay and
00:03:51.770
it's not really that helpful right never like oh that's all like desktop software like you know those Photoshop people are
00:03:57.560
let's not even talk about Windows you know but we kind of do the same thing to
00:04:02.750
two people I'd use our stuff it's like that's not helpful like given more rails
00:04:11.960
II stuff you know this is not the research here looking for I didn't even know I was looking for a resource but
00:04:17.150
thanks what do you do with this ring and
00:04:25.150
so I was starting to think like what's the problem like aside from the fact that these error messages are clearly
00:04:31.160
not helpful at all like why aren't they and I think the problem with these
00:04:39.770
messages is that they tell you what's the problem and I was like isn't that what you want
00:04:46.340
to know like there's there is an error and you kind of want to know what's the problem right I was like is that really
00:04:51.830
what you want to know and I started thinking some more about this because I was like huh I am frequently on the
00:04:58.640
receiving side of these error messages but since I'm a developer and probably also somebody who causes other people to
00:05:05.690
face these error messages I was like maybe there should be something done about it so I was kind of trying to take
00:05:11.270
a step back and with like if there's an error like what is this error and what
00:05:16.280
am I trying what am I trying to say about this error and who the hell am I even talking to and so I figured and I
00:05:28.250
was like okay Who am I talking to whenever I have an error there are probably some different audiences what
00:05:34.700
could these audiences be that would be interested in this error that just happened
00:05:40.800
so first of all we have the developer like we have a product we have an app or
00:05:45.990
something there's a person on the back end assuming we have a server client architecture there's a persona back-end
00:05:52.199
that writes this stuff and their job is to figure out how to fix errors that
00:05:58.440
shouldn't happen who else do we have we
00:06:04.949
have people that use our stuff if we have an API our product is an API or has
00:06:10.949
an API we have an API user and what they need to do is to figure out how to
00:06:16.349
correctly call the endpoints that we provide to them and get the response that they expect and last but not least
00:06:25.340
we have this guy if our thing is our product is an app a web app or a mobile
00:06:31.680
app or something we have the person that actually needs to figure out how to use
00:06:37.020
this app and how to do the things that we promised them they can do with our product so now we have our audience we
00:06:46.949
are the user than the developers different types of users the developer writes the thing now we have errors and
00:06:53.520
for this one I'm going to really generalize a lot but I feel like it's
00:06:59.190
helpful categories we have user errors I call them user
00:07:07.319
errors these are areas that are actually caused by the user by inputting things that are incorrect and these areas are
00:07:15.360
expected they have rules so we know like there's images and you should only
00:07:20.999
upload images up to like up to this size or you have to input something can be longer than this stuff like that you're
00:07:27.089
not supposed to use a credit card that's expired so it's not necessarily to use
00:07:32.099
its fault but they caused it and if they know the rules and they follow the rules maybe
00:07:38.129
that's a little German in me I'm like that's like I'll just follow the rules and everything is going to be okay but so if you follow the rules then the
00:07:45.300
error goes away and then we have this other type of error which I'm going to
00:07:51.990
call the server error for now it's stuff that tap that happens like in your code in the back end and it's unexpected it
00:08:00.870
has no rules like there's nobody then like no error message that you can possibly write for a bug that tells you right away like oh here's what it is and
00:08:07.949
this is how you fix it would be great but unfortunately doesn't usually happen so you actually need to go and
00:08:14.129
investigate if something like this happens before you can fix it
00:08:20.810
so our two types of errors are the user areas and server errors and now we can't write this up we have users we have
00:08:29.039
developers we have user errors and server errors and now we can think like who actually cares about all of this
00:08:36.149
stuff like who sees what and who's like oh this is my thing like I got deal with this
00:08:46.160
if I have a user that faces a user error that's something they can't fix they just need to input the right thing they
00:08:51.839
need to know what they should input and then do it a developer that writes this
00:08:58.949
code like at the point when the user actually input something you can't really stop them like there's nothing
00:09:05.339
you can do about it you can try to make it clear and everything but if they do something wrong you can't stop them so
00:09:10.589
you kind of can't really fix this on the other hand if you have a server error a
00:09:17.579
user can't really do anything about they can't go into your code and kind of try to fix the bug and you don't really want
00:09:23.309
to anyways you can and you must however fix your server errors like if there's a
00:09:29.309
bug you have to go and find it in fixes
00:09:34.579
so what you really care about as a user is the user errors these are the ones that you have to handle or deal with and
00:09:40.829
as a developer you milkweed want to know about the server errors and as we
00:09:47.730
already figured out server errors have bugs mostly you have to know what's the
00:09:54.000
problem because you have to figure out on your own like what's wrong you have to have all the information that you can
00:10:00.959
get to debug however as a user of an app
00:10:06.839
I have exactly zero interest in debugging this app that I'm using right
00:10:12.149
now or this API that I'm using right now I just want to use it
00:10:21.120
here we go so I don't really want to know what's the problem that's just a
00:10:27.510
step on the way what I really want to know is how do I make this problem go away and now if we look at this kind of
00:10:38.910
error message guess who wrote this the
00:10:44.130
person who wrote this is a person that is used to dealing with errors on their side where they don't really have a
00:10:49.680
solution of how to make it go away they just want to know what's the problem and that's what they tell the other person
00:10:56.279
as well for them however it's not actually what they want to know so if we
00:11:05.820
keep that in mind and look at it more on a I guess like a system level or a flow level this is my extremely creative flow
00:11:14.190
diagram when you have a request coming
00:11:20.010
in from some kind of interface like no matter is it like an API or like an app or whatever an error happens here what
00:11:30.690
do we do if this is an error that is actually
00:11:37.070
interesting for me the developer I got to log it like I got to be informed about this area I got to know what
00:11:42.890
happened so this is basically logging and you want to put everything there that tells this person what is the
00:11:49.490
problem on the other hand I also got to communicate it back to the interface and
00:11:56.770
here really don't wanna know what's the problem on to know how do I make it go away can I make it go away so we're
00:12:06.860
splitting this up we're defining what is this what kind of error is this and who am I talking to about designer
00:12:20.690
and now that we know that we can kind of think about a bit more how do we
00:12:28.399
communicate this because now we know what we want to say and to whom so what
00:12:38.300
about users as a developer is that something that interests me at all most
00:12:44.689
of the time I'm kind of like I don't really care however this is something
00:12:51.560
where that I've actually experienced on products that I've worked on if they're
00:12:57.860
if you constantly get input about users not being able to do a thing or they
00:13:03.439
always make errors they do the wrong thing you can kind of turn on to selectively log input errors like this
00:13:11.180
kind of errors on an info level to see how often they happen and at which point they happen and if you're like oh like
00:13:17.300
every second person like trying to do this gets it wrong then I have to rethink my interface then you go and
00:13:24.139
talk to the UX people or whoever made this thing to figure out how can we actually not make this happen so much
00:13:31.360
because we have to communicate the rules to the user but in this case me as a
00:13:38.000
developer I actually won't know how to not make it happen as the user on the other hand I'm concerned at this point
00:13:45.980
like how do I make it work so what do I want as an app user first of all I want
00:13:53.449
really clear and readable area layout I don't want to kind of try and have to
00:13:59.060
kind of look around and see what it actually is I want to see it right away and when it's super clear I want to
00:14:05.990
localize as possible if I have no way to
00:14:11.540
tell what kind of language this user speaks I have to make a reasonable
00:14:17.779
assumption about a default can be English depending on the country if
00:14:22.939
you're in a country where you can't assume everybody speaks English really well you have to then do something else
00:14:29.839
for example in Japan it's usually not a reasonable assumption to make English errormsgs you're probably one Japanese
00:14:36.400
and you really want to provide a clear course of action to solve the problem no
00:14:43.270
matter what it is you tell them like you uploaded something that is too big upload something that is maximum one
00:14:49.750
megabyte or like your credit card is expired use a credit card that is not expired he's a coupon that hasn't been used yet
00:14:55.780
whatever it is tell them what to do and that kind of ties in with the other one
00:15:02.620
like if you want to minimize these errors from happening in the first place
00:15:07.870
the best air is the area that never shows up that never happens so you want a lot of front-end validations for stuff
00:15:13.990
that you can validate in the front end and you want good UX for people to understand what they actually are
00:15:19.210
supposed to do if we have API users the
00:15:25.720
thing about them is they usually are developers also they just kind of can't
00:15:32.140
look into your source code they have to talk to you through this API interface so they kind of understand like you
00:15:38.230
don't have to guide them along that much because they're used to debugging also but you want to make it super easy for
00:15:45.550
them to know what went wrong and how they can make it right so use matching
00:15:50.800
HTTP status code there's actually so there's a service that I have had to use
00:15:58.420
at work and they have an API and this
00:16:03.880
API has an endpoint like MN point one and to tell the endpoint what to do is
00:16:12.490
you put into the body of your request an ID that says for example I want to do
00:16:18.730
like register something you put ID zero to two and like all the other parameters and then you send it and this endpoint
00:16:25.990
will always return 200 okay no matter what happens and then in the body of the
00:16:33.790
response you will have an error code if there wasn't there was a there is a result which is zero if everything was
00:16:40.270
alright one if there was an error then you have an error code which tells you what kind of area'd was and then you
00:16:45.310
have detail error code which tells you what kind of detail arid wasn't then you have to go and look at a gigantic list of
00:16:50.920
custom error codes to figure out what went wrong a person on Twitter it like I
00:16:57.790
shared this on Twitter and the person came up with the app description of this as 200 okay but so you can in like I
00:17:10.210
mean as if that's in the second point like put in specific error messages put all the custom codes you want but still
00:17:16.360
like make like use reasonable HTTP status codes like there's a reason why there why there are standards for this
00:17:23.530
right and include everything introduce your response that makes it clear what
00:17:28.630
to do like you say like parameter something is if you just say parameter you're missing that's not helpful
00:17:33.670
parameter blogs missing or validation fails because here is what like how to make a value of a valid request also
00:17:41.170
kind of like the front end validations on the app user side indigo DX right really clear documentation because API
00:17:49.600
users do occasionally read the manual so give them one it's going to be a lot
00:17:55.330
less trouble for you afterwards and
00:18:02.010
that's the API user
00:18:07.309
what about server errors as a developer
00:18:13.679
this is something I care about a lot because I need to fix them so you want
00:18:20.190
to make sure that your code has robust error handling like if there is a bug or
00:18:25.679
an unexpected error you want to kind of minimize the damage you don't want everything to crash and burn you want to
00:18:34.259
log it and report it like you use an air break or roll bar or whatever and include as much information as possible
00:18:41.129
like most of these services like they give you a gem or something that you can include and they already pull out a lot
00:18:47.609
of info like they give you the back trace they give you the actual error they give you the parameters and
00:18:53.970
everything but whatever else you have and you think might help you actually reconstruct this error and be able to
00:19:01.559
redo it and find what is the actual issue put it all in like send it to your
00:19:08.309
logging service to make sure that someone actually gets notified because
00:19:17.039
you can have all the logging in the world and all the error reporting in the world if nobody ever looks at it it's
00:19:23.549
kind of pointless so what we do for example we have our like we integrate our roll bar would wanna reflect
00:19:29.789
channels so whenever there's an error that happens for the first time that happens repeatedly we get notifications
00:19:36.359
on flag if it's a production system so all the developers are in that one and then you can actually go right away and
00:19:43.230
look at it and evaluate is it something that you can have to fix right now something that you can fix later and if
00:19:52.169
you want to if there was an actual bug that affected users you can then announce publicly on a change log for
00:19:59.759
example that it was fixed so people know hey it's not going to happen again
00:20:08.380
what about users and server errors it does impact them right I mean they
00:20:13.580
really don't want to know what went wrong because they can do nothing about it they do want to know kind of what's
00:20:20.990
going on especially tell them that it's not their fault because if something
00:20:27.320
goes wrong and you don't know the system behind it and you're especially if you're not a developer and you can't guess and you're maybe not even very
00:20:34.190
comfortable with software you're going to be really scheduling a lie Oh what happened like did I break it like did I break the Internet did I
00:20:40.460
break something and so you had to tell them hey this is what happened it's our
00:20:47.960
fault this is what to do next and it can be for example just try again later we're like over capacity we can't serve
00:20:56.300
you right now like just try again later or hey this is an actual problem with your stuff please contact support I
00:21:05.650
found this little cartoon and I thought that's quite descriptive because like this kind of stuff is scary to users so
00:21:13.520
if you just say oh error BAM they're like what am I going to do now what I'm going to do now did delete my data did
00:21:19.970
it charge my credit card the did charge it like five times can i order again like what do i do or
00:21:26.930
you just tell them hey something went wrong on our side you're safe just try again later and they're going to be like
00:21:33.080
show okay I'm good just go and try again later
00:21:40.740
so instead for example off sending something like this which is still scary
00:21:46.930
and I'm like to a developer it makes sense because yeah this is you know this is what happened to a person who doesn't
00:21:54.130
know it doesn't make any sense at all it's just scary stuff you did something wrong it said you do something like that
00:22:03.670
and you don't even have to go alright see like if you don't have somebody could draw you like flying whales you
00:22:09.910
know it's okay like you can just write the message like even if it's not nicely styled just say it it's going to do like
00:22:15.960
like I'm a firm believer in the 8020 rule like you know 20% of effort brings
00:22:21.490
you like 80% of the way so if you just say it no matter how it's already going
00:22:27.070
to be much much better
00:22:34.470
and this is pretty much where we're wondering for everybody who is interested everybody in our audience we
00:22:41.820
want to achieve or we want to enable them to solve the problem that they're facing in the best way possible in the
00:22:50.549
fastest way possible and with the minimum of frustration no matter if it's a developer if it's a user or anything
00:22:58.159
and now that we know what we want to say
00:23:03.450
about what kind of error to whom we can now go out and figure out how to write
00:23:09.090
the perfect error message how to word things how to display things but this step about like what am I going to
00:23:17.490
communicate to whom that's like that's been like the missing link for me of like going from an error happens to like
00:23:23.760
what kind of thing do I put into my error message and this is pretty much what I wanted to share with you so I
00:23:33.590
hope this is helpful to you when you handle your errors in the future and
00:23:38.630
communicate them to whoever is interested in them thank you awesome
00:23:48.059
stuff thanks for I think the great message you think about the people who know see you errors and give them some directional to
00:23:54.360
do next can we get some questions please anyone hasn't yes ok hi thank you for the talk
00:24:03.590
what do you think is the major problem with like because you showed the 500 in
00:24:08.730
rails error message and I mean I've seen it a million times and I think Oh what do you think is the
00:24:15.480
the reason for that because if I can make a comment I think most people don't know how to kind of I mean I wouldn't
00:24:22.590
know how to keep like how to track what error happened because you know you have
00:24:28.500
this 500 generic handler in rails and then once this exception is happening
00:24:33.600
you basically lose information of ok was it I don't know the wrong credit number credit card number or was it I don't
00:24:39.840
know a Redis connection broke or something like that so I think I'm
00:24:45.390
asking how two people trek what actually happened especially in rails trek is for like the
00:24:52.740
developer like whatever happen or a trek for the person who sees it on the front end so the developer has to basically
00:24:59.280
track what happened so you can render a meaningful error message well I think for I guess what I was trying to make
00:25:07.770
clear for 500 years I totally think we should talk German by the way like for
00:25:13.050
server errors there is you don't really want to so if it's a 500 then it's most
00:25:18.060
likely some kind of bug and you don't really have to communicate to the user hey this is exactly the bump that
00:25:23.610
happened because they don't really care there so it's not going to work for them until until you fix the bug so for a 500
00:25:29.610
error you just want to tell them hey something went wrong in our side so you
00:25:34.620
don't really need to figure out at this point what went wrong and show it to the user but you and the developer you need to know so you want the error handling
00:25:41.100
that actually like as the exception gets raised you catch it or you kind of handle it and log in to your logging
00:25:47.550
system so you can then get notified until okay this is where it happened this was the area this is the backtrack
00:25:52.920
okay okay okay I got it cool thanks yeah
00:26:00.170
do you think actually it is a good idea to tell the reverse try contacting us or simply Lotus or to try again later these
00:26:08.160
messages because I think that if you say try again later the users will just keep trying and these back is like you know
00:26:14.160
over and over and they are just frustrated because what does in later doesn't in five minutes or as many five
00:26:20.310
days and the other one is when we say contact us then suddenly we've got 50 emails from users saying hey I saw this
00:26:27.600
error but me as a developer I already saw it in my error tracker so the user actually doesn't have to contact me I
00:26:33.270
don't need it so do you think that doesn't it make users only more frustrated because they expect the
00:26:38.610
immediate response from you when they contact me yeah that's a good question and I think it really depends on the kind of area because I given on the
00:26:44.790
server you get different types of errors if it's a bug like an unexpected error like completely unexpected you got to
00:26:51.690
fix the bug like and they can't like they can retry all they want it's not going to make it go away however if it's for example because you
00:26:57.600
can't temporarily could reach some micro-service and it or something timed out and then you like
00:27:04.170
okay I know this is like a 504 you're like a 504 or something and then you know like okay if they try again is
00:27:09.630
probably going to work then you can tell them like oh just retry if it's
00:27:15.240
something where you really want to contact support that would probably be like if you can figure it out by the
00:27:20.250
type of error being races for example if you actually have a problem with your data you know I give something but
00:27:25.800
missing and they just trying to kind of actually get a research that's not there anymore but it should be there but they
00:27:30.810
did one fix itself it's not an actual like code error but it's more like a data error and you probably have to have
00:27:37.020
someone fix it for them like specifically for that person or for that user yes any other questions yeah the
00:27:54.840
gentleman looms are hi thank you for your talk it was exceptional thank you
00:28:04.880
all right I really enjoyed your presentation I was wondering for the category of
00:28:13.050
errors when we were just showing 500 pages where it's something that happened on the back end we don't we don't need
00:28:19.530
to inform the end-user what happened do you think that that's the type of
00:28:25.830
messaging that belongs on that page is generic enough that it could be similar
00:28:32.460
thing for all website I mean I guess what I'm trying to get to is is there a could we possibly change the 500 page
00:28:40.140
the default 500 page on Rails such that is there the production 500 page such
00:28:45.450
that it's better for end users by default is that something you think would be possible or does it have to be
00:28:51.600
customized per site I mean you can probably like if you want to do it like 100 percent you can probably customize
00:28:57.840
it precise but I think it could be a lot better as a default just because like if
00:29:03.600
I'm developing like if I'm doing it on my local machine and stuff and sure like as developer I know like this like
00:29:08.670
something like internal server error I know but like if it's displayed to a user in
00:29:14.800
production I think that's actually a very good idea to say something that
00:29:20.110
makes sense as like out of the box to a person who doesn't know what this is about
00:29:25.440
thank you I have one recommend I think
00:29:31.240
that if you have a website you have an application that processes users money
00:29:36.280
if you use credit cards or something to pay you and there is an error on the payment step
00:29:41.740
you shouldn't I'll contact us you should tell we will contact you like I think that it's just not developers that the
00:29:47.140
company is good practice to be proactive because users will panic if they'd see an error when they provided you their
00:29:54.040
credit card number just I think something special like if you actually managed to catch it some kind of error
00:30:00.460
that's not like I kind of know method error or something and you know that their payment wasn't processed or it
00:30:06.010
never even reached for example the payment at the credit card provider tell them especially about credit card
00:30:11.590
payments because that's like something that people like don't think it's funny at all like you try to buy something and you're like oh did it process like if I
00:30:18.490
order again like will they turn to me twice they're like what happened so and otherwise if you can't tell you got to
00:30:24.700
make it so that on the back end you're actually informed out like this was a process that involved payment an error
00:30:30.670
happened police check on this user was their payments did it go through or not
00:30:37.530
uh how how useful do you think HTTP status codes are to users I guess which
00:30:46.000
kind of losses so actual app users so I guess you still see quite a lot of 404
00:30:51.460
pages with the numbers 404 in them I'm just wondering is it is it so common
00:30:56.740
nowadays that people know the 404 means a page can't be found under is it still like our developer bias coming in so I
00:31:05.530
guess the thing with the 404 is that's kind of the one status code that's kind of ambiguous because it could be like
00:31:11.890
this page doesn't exist like this path per se or like this actual resource that
00:31:17.560
I was trying to find doesn't exist so that's one of the bit more like difficult ones but basically it says
00:31:23.620
like some wasn't found I don't think the number means anything to people it just kind of
00:31:29.299
shows up and right a lot of websites to is like oops we couldn't find what you were looking for because of something
00:31:35.120
and then you still kind of I think it's better to actually say like hey what should you do if you can do something
00:31:41.510
but like the number per se I don't think it means anything unless you target like your target audience is actually
00:31:47.179
developers like if your github like people who use your service are developers so they're going to know what is 404 but if it's something completely
00:31:54.019
unrelated this I think the number it probably doesn't mean anything to actually end users cool
00:32:03.590
I think there's time for one last question there is any do if anyone else
00:32:09.169
with questions no okay thank you very