Well, I was looking through the MSDN Library docs that came with MSVC++ 6 today, and found a section which was about writing 'good error messages.'
Microsoft seems to give many different rules regarding writing error messages, but they seem to be hypocrites as they don't even follow their own rules.
I'll post a few highlights from this section, and mention why I think these rules are wrong.
Do not anthropomorphize. Do not imply that programs or hardware can think or feel. For example, avoid a message such as the following:
[node name] node does not speak any of our protocols
Instead, write a message such as:
Node [node name] cannot use Windows NT protocols
Many, many pieces of software written for Unix based systems do this. I think it might make the user feel more at ease with the computer hardware, perhaps giving the errors feeling, like they were written by a real person rather than just being another string of text spit out by the machine.
Use full sentences. For example, use "Binding is too long" instead of "Binding too long."
Microsoft is hypocritical here. For an example, go to Start>Run, press browse and enter an invalid filename. When you try to hit enter or click OK, it gives a message that reads 'File not found'. I wouldn't call that a complete sentence.
Place a searchable word at the start of each message. Avoid starting a message with an article. (the, a, or an). Never put a placeholder variable, such as %1 or %2, at the beginning of a message, since this makes it very difficult for a user to look up the message in our Help File. Instead, write the message so that a searchable word is at the beginning and the placeholder is embedded in the message. For example:
Log file %1 is full.
NOT: %1 log file is full.
First of all, doesn't that contradict the 'complete sentences' rule? Also, I didn't know an error message from MY program could be looked up in THEIR help file. For example, "Map redrawing failed" in the mapper isn't going to find me anything in Windows help.
Users almost always prefer simple sentences that use simple present or past tense and active voice. For example:
Registry Editor cannot create the subkey.
NOT: ...could not create...
Setup cannot start Program Manager.
NOT: Setup was unable to activate Program Manager.
... I never cared whether it said "cannot" or "could not." Besides, in a program, you have to try the action before you can display the error message if it failed, so that would be the attempted action occurred BEFORE the error was displayed.
Event logging in Microsoft Windows NT provides a standard, centralized way for applications and the operating system to record important software and hardware events. It also provides a standard user interface for viewing the logs and a programming interface for examining the logs. Event logging provides a means to merge events from various sources into a single informative story.
I highly doubt the average windows user even knows how to access the event log.
Do Use the Following Good Words
click
Do not use click on.
disk
Do not use diskette.
hard disk, or hard disk drive
Do not use hard drive, internal drive, fixed drive, or hard disk system.
MS-DOS
Do not use just DOS.
"Click the button" versus "Click on the button"? Don't see much difference there.
Diskette? if the user doesn't know what 'diskette' means, I'd be really surprised.
Hard drive? again, what's the difference?
MS-DOS? Of course, we cannot acknowledge that there are flavors of DOS other than those made by Microsoft (such as PC-DOS by IBM, and the opensource FreeDOS)
quit
You quit a program (not close, end, exit, leave, stop, or terminate).
Registry
Registry always has a capital "R".
stop
You stop a hardware program. For example, you "stop a print job."
Quit? well, right click the title bar of the main window of any program. You'll see the word, "Close." 'Nuff said.
Registry? I don't have enough respect for that hunk of junk to write it with a capital r.
stop? In the printers and faxes window, when you right click a print job, it gives you "Cancel" as one of the choices, not stop.
---
Anyway, just more examples of Microsoft's vast profits, but not much to do with them.
