TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
The message text you include in a message box should be clear, concise, and
in terms that the user understands. This usually means using no technical
jargon or system-oriented information.
In addition, observe the following guidelines for your message text:
State the problem, its probable cause (if possible), and what the user can
do about it -- no matter how obvious the solution may seem to be. For
example, instead of "Insufficient disk space," use "'Sample Document' could
not be saved, because the disk is full. Try saving to another disk or
freeing up space on this disk."
Consider making the solution an option offered in the message. For example,
instead of "One or more of your lines are too long. The text can only be a
maximum of 60 characters wide," you might say, "One or more of your lines
are too long. Text can be a maximum of 60 characters in Portrait mode or 90
characters wide in Landscape. Do you want to switch to Landscape mode now?"
Offer Yes and No as the choices.
Avoid using unnecessary technical terminology and overly complex sentences.
For example, "picture" can be understood in context, whereas "picture
metafile" is a rather technical concept.
Avoid phrasing that blames the user or implies user error. For example, use
"Cannot find filename" instead of "Filename error." Avoid the word "error"
altogether.
Make messages as specific as possible. Avoid mapping more than two or three
conditions to a single message. For example, there may be several reasons
why a file cannot be opened; provide a specific message for each condition.
Avoid relying on default system-supplied messages, such as MS-DOS® extended
error messages and Kernel INT 24 messages; instead, supply your own specific
messages wherever possible.
Be brief, but complete. Provide only as much background information as
necessary. A good rule of thumb is to limit the message to two or three
lines. If further explanation is necessary, provide this through a command
button that opens a Help window.
You may also include a message identification number as part of the message
text for each message for support purposes. However, to avoid interrupting
the user's ability to quickly read a message, place such a designation at
the end of the message text and not in the title bar text.
