The example provides the same error information three times ("EPERM", "Invalid permissions on myfile.out", "Cannot write to myfile.out, file does not have write permissions"), followed by a recommendation that might not be correct.
Yes, this is an example, but surely you'd want an example that shows the strength of doing this verbosely? A good example of a verbose error message system is Rust's compiler output (or newer clang/gcc outputs). Being verbose for no reason other than to be verbose is just wasting the users' time (or they just ignore the spam -- which is what I would do if I used a tool that spammed me with multiple lines of output whenever it hit an -EPERM).
Personally, something like:
% foo ./bar
foo: write config to "./bar": Permission denied
Is clearer to me than your example. Maybe something like
% foo ./bar
foo: write config to "./bar": Permission denied
Hint: Have you tried <possible-recommendation>?
Is sometimes okay (and I have done this for my own projects as well), but it's something that should be done in moderation...
> You're much more likely to be helpful to a confused user than someone grepping logs and looking for terse output on a single line.
There are two sides to this. Outputting lots of text can also cause a user to get confused (if we're talking about making things easy for not-necessarily-technical users).
When teaching (high-school) students to program, we quickly learned that even somewhat verbose output like Python's stacktraces can cause students to suddenly become anxious because there's a pile of text on their screen telling them they did something wrong. Adding more text to output does not always help, and you should keep that in mind.
Yes, this is an example, but surely you'd want an example that shows the strength of doing this verbosely? A good example of a verbose error message system is Rust's compiler output (or newer clang/gcc outputs). Being verbose for no reason other than to be verbose is just wasting the users' time (or they just ignore the spam -- which is what I would do if I used a tool that spammed me with multiple lines of output whenever it hit an -EPERM).
Personally, something like:
Is clearer to me than your example. Maybe something like Is sometimes okay (and I have done this for my own projects as well), but it's something that should be done in moderation...> You're much more likely to be helpful to a confused user than someone grepping logs and looking for terse output on a single line.
There are two sides to this. Outputting lots of text can also cause a user to get confused (if we're talking about making things easy for not-necessarily-technical users).
When teaching (high-school) students to program, we quickly learned that even somewhat verbose output like Python's stacktraces can cause students to suddenly become anxious because there's a pile of text on their screen telling them they did something wrong. Adding more text to output does not always help, and you should keep that in mind.