Re: Error Message Appendix
For the software I currently document, the engineers have written a large number of error messages that appear when a user performs a task incorrectly.
For instance, an error message will pop up on the screen when a user neglects to import a required file or types a number that is outside the minimum and maxiumum allowed values for a certain parameter.
We've received feedback from customers that the error messages are not descriptive enough, and we're working on making the messages more comprehensible so users know exactly what went wrong and how to fix the problem.
I'm wondering if anyone has ever included an appendix in their documentation listing each error message in the source code, along with more extensive descriptions of the solutions to each problem?
I think that what you initially need is for the programmers to write error messages that are useful to the user. In this day and age, the programmer should know enough that saying it is an overflow error is only meaningful to a programmer who is debugging the program.
The error message should say what is wrong, and what you need to do to avoid this error. Somethings, system errors that occur without the user doing anything wrong have to be explicit about that. You will find that that is potentially damaging to the company's reputation, if you make buggy software.
The messages obviously need to be meaningful to the average user. Keep it simple, don't talk in programer terms.
Other than that you have pretty much answered your own question in your example. The error message should say:
"Entered value is not within the acceptable range. Re-enter a number, from 25 to 35."
The appendix way is more for reference guides for programers. The user need the onscreen error message to tell them what is wrong and what to do to make it better.
Collect Royalties, Not Rejection Letters! Tell us your rejection story when you submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of your book. What are you waiting for? http://www.iuniverse.com/media/techwr
Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ and check it out.
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
Error Message Appendix: From: Dave Stewart
Search our Technical Writing Archives & Magazine