Gripping Reading, All The Way Through!
Your system throws up an error message. It's tempting to read the first few words and jump to a conclusion. 'Oh I know what that is...' But you really have to read the entire error message. Often the best bit isn't until the very end. Error messages are not like those predictable hollywood films that you can walk out of before the end, and still know exactly how it finished up. "Oh yeh, they defused the bomb, he got the girl and the dog learnt a new trick." Here's two messages I had yesterday:
Could not open new database 'C:\{...Path to Database..}\DATABASENAME.MDF'. CREATE DATABASE is aborted.
An attempt to attach an auto-named database for file C:\{...Path to Database..}\DATABASENAME.mdf failed. A database with the same name exists, or specified file cannot be opened, or it is located on UNC share.
File activation failure. The physical file name "C:\{...Path to Database..}\DATABASENAME_log.ldf" may be incorrect.
The log cannot be rebuilt when the primary file is read-only.
In this case, those last few words pinpointed the exact cause of the problem. Not long after that, I got this message: Timeout expired. The timeout period elapsed prior to completion of the operation or the server is not responding.
Exclusive access could not be obtained because the database is in use.
Again, it was the final words that pinpointed the problem. It's so easy to read the first few words and start making assumptions. In the first example the assumptions might be "oh, i must have the wrong name for the log file". In the second case the wrong assumption is "oh, the query is taking too long and needs to be 'optimised'..." I've said before that you have to read the error messages. I'll add now that you have to read the entire error message. (names of databases have been changed to protect the data)
'SimonH' on Wed, 30 Aug 2006 06:32:50 GMT, sez: After reading Joel Spolsky's site until my eyes go funny, it occurs to me that there's a usability issue here that we can learn something from.
"Users don't read.", JS
We can add that "even if users do read your message, they are only going to read the first few words. You need to catch them there."
So, when writing error messages, put the cause of the error first - Cause -> effect.
"The primary file is read-only: The log cannot be rebuilt.
Could not open new database 'C:\{...Path to Database..}\DATABASENAME.MDF'. CREATE DATABASE is aborted.
..." etc.
'Kev' on Wed, 30 Aug 2006 09:45:15 GMT, sez: Yep...I did the same with:
System.Security.SecurityException was unhandled by user code
Message="Request for ConfigurationPermission failed while attempting to access configuration section 'someSettings/theSettings. To allow all callers to access the data for this section, set section attribute 'requirePermission' equal 'false' in the configuration file where this section is declared."
I read as far as "..ConfigurationPermission failed while attempting to access configuration section 'someSettings/theSettings." then spent 20mins staring at the web.config file before going back to re-read the exception in it's entirety. That'll learn me.
'Chris' on Wed, 30 Aug 2006 14:00:32 GMT, sez: Any error message longer than one line is too long. In fact, that probably goes for any instructions as well. And no cheating by making your dialogs and lines as wide as the entire screen!
'Mary' on Fri, 13 Oct 2006 22:26:42 GMT, sez: very helpful!
better than windows unhelpful error messages. Logs are better!
mine here:
http://www.thatdamnpc.com/wp-content/uploads/2006/10/office2003updatemsg.jpg
more: http://www.thatdamnpc.com/troubleshoot-microsoft-windows-office-updates/
you might enjoy the "interface hall of shame"
http://homepage.mac.com/bradster/iarchitect/errormsg.htm
|
secretGeek .:dot Nuts about dot Net:.
Just Wally
Complete secretGeek Archives
The Best Software Writing I
The Business Of Software (Eric Sink)
