5 ms·

This just means that the error message needs to be more clear. For example, after the error itself, it could give direct advice: “PERFORM THESE STEPS: You must

This just means that the error message needs to be more clear. For example, after the error itself, it could give direct advice: “PERFORM THESE STEPS: You must define ENVVAR. Go to <wiki link>. Set ENVVAR to a proper value and restart the service.” Notice the direct language. It reads like an order. The less direct the message, the higher the chances that the user will not act upon it.

dvtrn 4y ago
I’m not seeing how what the message already is any less direct or clear than what you’re saying it should be? It straight up tells you it can’t find the var and what to do about it. Can you help me understand what isn’t clear about the message as is, or maybe point out the ambiguity to someone who just isn’t seeing it? I want to write better error messages but I share the frustration of the above poster. The message tells you specifically what to do, but you’re coming back saying it’s not clear.
- lupire 4y ago
  Some people don't read anything that isn't an all-caps command. They have learned helplessness from seeing too much useless error text in the past.
- j-bos 4y ago
  I think the original error is quite clear, under normal circumstances. Not OP but I've noticed that people often get brain fog when something goes wrong and are often need BIG, SHORT, WORDS to shake out of it. Or really anything that can shake them out of the 'idunno' state of mind. But maybe if something like that became standard ut would no longet be a context switcher..
  - ckozlowski 4y ago
    I think you're spot on, and I made a similar comment above. It's easy to say "they can figure it out". Sure, in a restful state. But the people we're asking to take action already have a lot on their plate. Using plain, conversational language whenever possible with exceedingly clear steps means less mental exertion on the receiver. And since we need their help, anything we can do to make it easier on their end helps us.
    - dvtrn 4y ago
      These are fascinating responses to me, as with the example given my mind first went to someone for whom English is a second language. that group having trouble with this message I would understand, or at least have an easier time understanding having trouble, if even a very little amount. For someone who was born speaking English and spoke it their entire lives, the example provided couldn’t possibly be more to the point in my opinion. Though I agree overall with the general idea and that yes there are some pretty baffling and downright awfully written error messages and log entries that take a minute to grok (I just don’t think the example replied to is one of them).
    - Too 4y ago
      Conversational errors can also be fatiguing. Often what you want is something short and dry that can be pattern matched. Compilers are pretty good at this because all their errors start the same way. Error in file foo/bar.c, line 32, missing semicolon. No conversation needed. These can then be complemented with more conversational language on the next line to explain why semicolon is needed. Rust is quite good at this.
      - randomswede 4y ago
        Then there's the delightful (no, I actually mean the opposite) errors that g++ emitted (back when I last wrote C++ and compiled using g++), where I basically could go "OK, there is an error that was detected at line L, in file F; and I think it may be a type error", so a recompile with clang, so I can actually understand what the error was, so I could fix it.
mariusmg 4y ago
>it could give direct advice: “PERFORM THESE STEPS: You must define ENVVAR. Go to <wiki link>. Set ENVVAR to a proper value and restart the service.” Really, should logs also be documentation now ? Just mindlessly logging the same "advice" over and over again each time the error happen ?
- dementiapatent 4y ago
  It will be so much fun when the implementation is refactored and half of these comments are forgotten about and no longer meaningful.
  - prerok 4y ago
    Exactly. At one of my previous workplaces there was a cumulative effect of misattributed error messages so the actions to perform were often of no help. Not even to mention the fact that new or changed error messages caused a landslide in costs in translations to various languages. I guess this product has no localization? At that time, when I was working at such a product that had it, we had to go through a deliberate process to describe why we want to change it, what the impact is, etc. Tell me you want 100 new messages and you will be stuck in meetings for the next month. In their case, though, it seems they at least have the support in management for it. I hope it turns out better for them than it did for me.
    - SpicyLemonZest 4y ago
      I had an error message a few months ago that instructed me to reinstall the AWS CLI, I filed a ticket when that didn't work, and the team was annoyed with me because obviously the real problem was a Python configuration warning with no suggested action 10 lines up.
- ddulaney 4y ago
  Logs can definitely be a form of documentation. I write software that is generally run low in the stack, quietly doing some mundane tasks that are business-critical but rarely thought about. If one of our clients has to mess with our software beyond the occasional update, that was a failing. Not all software is like this, but lots of it is -- its value is that no human needs to be involved. I need to write log messages with the expectation of an audience who doesn't know much about the software -- it's been running uninterrupted for months or years and suddenly something has gone wrong. If the log line doesn't tell the user how to solve their problem, I will end up getting a call.
pydry 4y ago
It more likely means that the developer views the service as OP's responsibility. They'll view an order as something OP needs to do. The clarity of the error message doesnt really matter if the recipient believes it is intended for somebody else.
ckozlowski 4y ago
I think you're correct. To add to this (and I think it's the point that the article was trying to make), errors written in fragmented language or "developer speak" I feel are likely to get glossed over. The “Write it like you’re talking to a friend.” advice the article gives I think is spot on. Making the message more conversational is to invite better understanding and comprehension. I feel there's a trend when it comes to disseminating messaging like this that we adopt an attitude of our audience "is smart, and should figure the rest out". They may be. But they already have lots to do any plenty to figure out. Any opportunity we, the requestor, can lighten their mental load, is going to increase the odds that they'll be inclined to take action right away.
MiddleMan5 4y ago
I can't tell if this is sarcasm or not, this is obviously highlighting a deeper issue in developer culture. The example given was clear compared to 90% of other error messages, and saying that it needs to be "more clear" is almost dismissive
- Aperocky 4y ago
  Don't blame developer culture, if that error cannot be acted on, attribute to incompetence and not culture.
duxup 4y ago
The problem is people are not rational… and we try to solve that with software. Many people just lock up when software doesn’t do what they expect.
- vbezhenar 4y ago
  Not rational people must be fired from IT.
  - duxup 4y ago
    Generally a pipe dream in my experience.
- hinkley 4y ago
  Lots of people find ways to irrationalize being rational.
bombcar 4y ago
Some of the errors that Gentoo portage can encounter do exactly this - and they do it with beautiful terminal colors that make it easy to figure out what you need to run, or where to go to figure out which of the three options you need. The problem can come when there's a wall of "useless" logging/error messages, and the last one or near the last one is the actual important one to look at. You have to explicitly call it out on a clear screen and make it obvious - and even then, people won't always read it.
bee_rider 4y ago
There's a type of error for which the user can be given detailed step-by-step instructions (permission issues, etc). But to some extent, errors should handle situations the programmer didn't expect. If it is possible to provide detailed step-by-step fixes, then the program should do those steps itself. Adding a URL might not be a great plan, never know how long an old copy of a program will stick around, might not control that website forever.

dvtrn 4y ago

I’m not seeing how what the message already is any less direct or clear than what you’re saying it should be? It straight up tells you it can’t find the var and what to do about it. Can you help me understand what isn’t clear about the message as is, or maybe point out the ambiguity to someone who just isn’t seeing it? I want to write better error messages but I share the frustration of the above poster. The message tells you specifically what to do, but you’re coming back saying it’s not clear.

lupire 4y ago
Some people don't read anything that isn't an all-caps command. They have learned helplessness from seeing too much useless error text in the past.
j-bos 4y ago
I think the original error is quite clear, under normal circumstances. Not OP but I've noticed that people often get brain fog when something goes wrong and are often need BIG, SHORT, WORDS to shake out of it. Or really anything that can shake them out of the 'idunno' state of mind. But maybe if something like that became standard ut would no longet be a context switcher..
- ckozlowski 4y ago
  I think you're spot on, and I made a similar comment above. It's easy to say "they can figure it out". Sure, in a restful state. But the people we're asking to take action already have a lot on their plate. Using plain, conversational language whenever possible with exceedingly clear steps means less mental exertion on the receiver. And since we need their help, anything we can do to make it easier on their end helps us.
  - dvtrn 4y ago
    These are fascinating responses to me, as with the example given my mind first went to someone for whom English is a second language. that group having trouble with this message I would understand, or at least have an easier time understanding having trouble, if even a very little amount. For someone who was born speaking English and spoke it their entire lives, the example provided couldn’t possibly be more to the point in my opinion. Though I agree overall with the general idea and that yes there are some pretty baffling and downright awfully written error messages and log entries that take a minute to grok (I just don’t think the example replied to is one of them).
  - Too 4y ago
    Conversational errors can also be fatiguing. Often what you want is something short and dry that can be pattern matched. Compilers are pretty good at this because all their errors start the same way. Error in file foo/bar.c, line 32, missing semicolon. No conversation needed. These can then be complemented with more conversational language on the next line to explain why semicolon is needed. Rust is quite good at this.
    - randomswede 4y ago
      Then there's the delightful (no, I actually mean the opposite) errors that g++ emitted (back when I last wrote C++ and compiled using g++), where I basically could go "OK, there is an error that was detected at line L, in file F; and I think it may be a type error", so a recompile with clang, so I can actually understand what the error was, so I could fix it.

mariusmg 4y ago

>it could give direct advice: “PERFORM THESE STEPS: You must define ENVVAR. Go to <wiki link>. Set ENVVAR to a proper value and restart the service.” Really, should logs also be documentation now ? Just mindlessly logging the same "advice" over and over again each time the error happen ?

dementiapatent 4y ago
It will be so much fun when the implementation is refactored and half of these comments are forgotten about and no longer meaningful.
- prerok 4y ago
  Exactly. At one of my previous workplaces there was a cumulative effect of misattributed error messages so the actions to perform were often of no help. Not even to mention the fact that new or changed error messages caused a landslide in costs in translations to various languages. I guess this product has no localization? At that time, when I was working at such a product that had it, we had to go through a deliberate process to describe why we want to change it, what the impact is, etc. Tell me you want 100 new messages and you will be stuck in meetings for the next month. In their case, though, it seems they at least have the support in management for it. I hope it turns out better for them than it did for me.
  - SpicyLemonZest 4y ago
    I had an error message a few months ago that instructed me to reinstall the AWS CLI, I filed a ticket when that didn't work, and the team was annoyed with me because obviously the real problem was a Python configuration warning with no suggested action 10 lines up.
ddulaney 4y ago
Logs can definitely be a form of documentation. I write software that is generally run low in the stack, quietly doing some mundane tasks that are business-critical but rarely thought about. If one of our clients has to mess with our software beyond the occasional update, that was a failing. Not all software is like this, but lots of it is -- its value is that no human needs to be involved. I need to write log messages with the expectation of an audience who doesn't know much about the software -- it's been running uninterrupted for months or years and suddenly something has gone wrong. If the log line doesn't tell the user how to solve their problem, I will end up getting a call.

pydry 4y ago

It more likely means that the developer views the service as OP's responsibility. They'll view an order as something OP needs to do. The clarity of the error message doesnt really matter if the recipient believes it is intended for somebody else.

ckozlowski 4y ago

I think you're correct. To add to this (and I think it's the point that the article was trying to make), errors written in fragmented language or "developer speak" I feel are likely to get glossed over. The “Write it like you’re talking to a friend.” advice the article gives I think is spot on. Making the message more conversational is to invite better understanding and comprehension. I feel there's a trend when it comes to disseminating messaging like this that we adopt an attitude of our audience "is smart, and should figure the rest out". They may be. But they already have lots to do any plenty to figure out. Any opportunity we, the requestor, can lighten their mental load, is going to increase the odds that they'll be inclined to take action right away.

MiddleMan5 4y ago

I can't tell if this is sarcasm or not, this is obviously highlighting a deeper issue in developer culture. The example given was clear compared to 90% of other error messages, and saying that it needs to be "more clear" is almost dismissive

Aperocky 4y ago
Don't blame developer culture, if that error cannot be acted on, attribute to incompetence and not culture.

duxup 4y ago

The problem is people are not rational… and we try to solve that with software. Many people just lock up when software doesn’t do what they expect.

vbezhenar 4y ago
Not rational people must be fired from IT.
- duxup 4y ago
  Generally a pipe dream in my experience.
hinkley 4y ago
Lots of people find ways to irrationalize being rational.

bombcar 4y ago

Some of the errors that Gentoo portage can encounter do exactly this - and they do it with beautiful terminal colors that make it easy to figure out what you need to run, or where to go to figure out which of the three options you need. The problem can come when there's a wall of "useless" logging/error messages, and the last one or near the last one is the actual important one to look at. You have to explicitly call it out on a clear screen and make it obvious - and even then, people won't always read it.

bee_rider 4y ago

There's a type of error for which the user can be given detailed step-by-step instructions (permission issues, etc). But to some extent, errors should handle situations the programmer didn't expect. If it is possible to provide detailed step-by-step fixes, then the program should do those steps itself. Adding a URL might not be a great plan, never know how long an old copy of a program will stick around, might not control that website forever.