Error handling and exposure are challenging to even implement much less *get right* in a piece of software - especially recently as software increasingly exists as productivity increasing glue between applications and services.
(Perhaps overly?) Defensive programming with consistency in delivering actionable information to users at not only a level of understanding, but a level at which *they care* is crucial. If you’re maintaining cURL you’re probably going to want to expose corresponding HTTP error codes - if you’re building a website your users probably don’t care about an HTTP 401 or 403 - they should just be shepherded to a login page.
Microcopy is a term used to capture those small pieces of text that guide users through an application or software - including error messages. It’s hard to get right, and it’s great to think about them across the various levels of technical understanding of a piece of software.
I’ve tried to build software to a point where I don’t get phone calls - basically aiming to deliver decipherable predictable decently documented tools with an error implementation that makes them supportable by the people with an intermediate understanding of the space between users and myself.
"Microcopy" never heard this term, I love that it exists, thank you for sharing this!!
I also 💯 love your goal of creating software that helps people help themselves. I think startups tend to do this far better than big co (thinking about internal tools specifically) because they don't have tons of engineers just sitting around to fix stuff. People need to unblock themselves, and to do that they need enough information about what happened, what went wrong, so they can maybe come up with their own workarounds.
if we treat external users this way, I think everything gets better
How about a compromise between computer terms they don't understand *enough* and actual meaning? Logic! After that, here is my conundrum, what perspective to use? Usually, it's objective and impersonal.
"This message has been deleted"
But some person, some programmer developer DID write that. The error is NOT an impersonal error, it was human reviewed and caught. Is it actually disengenous to make the human speech, robot speech?
We've deleted this message.
Hmm, responsiblity was taken there, that's new. The message did not delete itself. You [user] asked us [service] to delete it with a button that says "DELETE" and we did.
"We deleted this message at your request, but you have a temporary copy on this device. Last chance to copy the message and save it somewhere before exiting this interface ."
Something like that, I wrote that out quickly but I added some perceptual *impact* and recommended *action* for general users who will now understand.
So I created a personal interaction, I showed the user I am responsible for my systems behavior and know it well, and I gave impact and action.
this is interesting because I initially saw the passive "has been deleted" as appropriate! My thinking was, this is like a 404 situation, maybe the flow of the code here _expects_ something to exist, but it does not seem to. I guess in that case you should just articulate the simplest true thing which is, the message is could not be found on the server.
I wonder if "We deleted this message at your request" isn't quite right because, in the "correct" flow the local copy would be deleted along with the server copy. My interpretation (which could be wrong) was that this is a state where a message exists locally but not remotely, and the software wants to resolve this out of sync situation
> I showed the user I am responsible for my systems behavior and know it well
this made me think about what it's like at a big tech company where that isn't always true! I think individual engineers rarely feel amount of ownership & responsibility over the whole system. I think they default to "given this input, we are in an error state, I don't know how we got here" (because a lot of it is outside their team's control and they generally are kind of silo'd)
There is a typo in the 1st quote. It says: “And there are not sixty two kinds of particles, [...].” But is should, instead, say: “And there are now sixty two kinds of particles, [...].”
Great article!
Error handling and exposure are challenging to even implement much less *get right* in a piece of software - especially recently as software increasingly exists as productivity increasing glue between applications and services.
(Perhaps overly?) Defensive programming with consistency in delivering actionable information to users at not only a level of understanding, but a level at which *they care* is crucial. If you’re maintaining cURL you’re probably going to want to expose corresponding HTTP error codes - if you’re building a website your users probably don’t care about an HTTP 401 or 403 - they should just be shepherded to a login page.
Microcopy is a term used to capture those small pieces of text that guide users through an application or software - including error messages. It’s hard to get right, and it’s great to think about them across the various levels of technical understanding of a piece of software.
I’ve tried to build software to a point where I don’t get phone calls - basically aiming to deliver decipherable predictable decently documented tools with an error implementation that makes them supportable by the people with an intermediate understanding of the space between users and myself.
"Microcopy" never heard this term, I love that it exists, thank you for sharing this!!
I also 💯 love your goal of creating software that helps people help themselves. I think startups tend to do this far better than big co (thinking about internal tools specifically) because they don't have tons of engineers just sitting around to fix stuff. People need to unblock themselves, and to do that they need enough information about what happened, what went wrong, so they can maybe come up with their own workarounds.
if we treat external users this way, I think everything gets better
How about a compromise between computer terms they don't understand *enough* and actual meaning? Logic! After that, here is my conundrum, what perspective to use? Usually, it's objective and impersonal.
"This message has been deleted"
But some person, some programmer developer DID write that. The error is NOT an impersonal error, it was human reviewed and caught. Is it actually disengenous to make the human speech, robot speech?
We've deleted this message.
Hmm, responsiblity was taken there, that's new. The message did not delete itself. You [user] asked us [service] to delete it with a button that says "DELETE" and we did.
"We deleted this message at your request, but you have a temporary copy on this device. Last chance to copy the message and save it somewhere before exiting this interface ."
Something like that, I wrote that out quickly but I added some perceptual *impact* and recommended *action* for general users who will now understand.
So I created a personal interaction, I showed the user I am responsible for my systems behavior and know it well, and I gave impact and action.
this is interesting because I initially saw the passive "has been deleted" as appropriate! My thinking was, this is like a 404 situation, maybe the flow of the code here _expects_ something to exist, but it does not seem to. I guess in that case you should just articulate the simplest true thing which is, the message is could not be found on the server.
I wonder if "We deleted this message at your request" isn't quite right because, in the "correct" flow the local copy would be deleted along with the server copy. My interpretation (which could be wrong) was that this is a state where a message exists locally but not remotely, and the software wants to resolve this out of sync situation
> I showed the user I am responsible for my systems behavior and know it well
this made me think about what it's like at a big tech company where that isn't always true! I think individual engineers rarely feel amount of ownership & responsibility over the whole system. I think they default to "given this input, we are in an error state, I don't know how we got here" (because a lot of it is outside their team's control and they generally are kind of silo'd)
thank you for sharing your thoughts 🙏
"If it does not need to be correct, it can be arbitrarily simple"
Bad error messages are the root of all evil. People who do not study bad error messages will be be forced to endure them, as will everyone else.
There is a typo in the 1st quote. It says: “And there are not sixty two kinds of particles, [...].” But is should, instead, say: “And there are now sixty two kinds of particles, [...].”
thank you, fixed!!
There is a typo in your comment about a typo.
You wrote:
“But is should, instead, say:…”
But it should, instead, say:
“But it should, instead, say…”
“There is a typo in your comment about a typo.”
Also known as Muphry’s Law
Fantastic stuff. This is the kind of mindset we're having when making the alignment guides.
- kabir
@WillTurman
You cite Murphy's Law but, rather , I think O'Flarrety's Law fits better.
O'Flarrety's law states:Murphy was an optimist.