About

I'm Mike Pope. I live in the Seattle area. I've been a technical writer and editor for over 30 years. I'm interested in software, language, music, movies, books, motorcycles, travel, and ... well, lots of stuff.

Read more ...

Blog Search


(Supports AND)

Google Ads

Feed

Subscribe to the RSS feed for this blog.

See this post for info on full versus truncated feeds.

Quote

Try a thing you haven't done three times.
Once, to get over the fear of doing it.
Twice, to learn how to do it.
And the third time, to figure out whether you like it or not.


Robert Evans



Navigation





<December 2023>
SMTWTFS
262728293012
3456789
10111213141516
17181920212223
24252627282930
31123456

Categories

  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  

Contact Me

Email me

Blog Statistics

Dates
First entry - 6/27/2003
Most recent entry - 11/30/2023

Totals
Posts - 2652
Comments - 2670
Hits - 2,621,097

Averages
Entries/day - 0.36
Comments/entry - 1.01
Hits/day - 351

Updated every 30 minutes. Last: 12:23 AM Pacific


  12:40 PM

The ever-interesting Eric Lippert has a thoughtful post on how to create good error messages. His particular focus is on the error messages generated by a compiler, but there's very little in there, save perhaps the actual examples, that wouldn't apply to most situations.

His thesis in a nutshell is that error messages should be:
  • Polite
  • Readable
  • Accurate
  • Precise
  • Diagnostic but not prescriptive
... and I'll refer you to his post for the definitions and distinctions of these and for examples.

The last one, as he predicts, is probably the one that is likeliest to be debated by error message authors. The problem with being prescriptive, of course, is that you don't necessarily know what the user is doing, so it can be hard to tell them what to fix. For that matter, in many contexts you don't necessarily know what the problem is exactly; you might just know that something has gone awry. A classic example of this last is the error message you might sometimes see:

The type or namespace name 'some name' could not be found (are you missing a using directive or an assembly reference?)

I like this because it's diagnostic -- the message tells you exactly what the compiler doesn't recognize. But it's also ... well, not prescriptive, exactly, but, you know, helpful -- "People who see this message often see it because xxxx!" That is, it points you at what is probably the most common source of this error without telling you that that's your problem.[1]

Of course, no error message is any good if people don't read it at all. As Leon recently pointed out, those ASP.NET YSOD error messages have all sorts of useful information in them. When Eric and his team get done with revamping the C# compiler, they'll be even better ...


[1] Is it just me, or is that reference to the "using" directive C#-centric?

[categories]   , ,

[1] |