Showing posts with label style guide. Show all posts
Showing posts with label style guide. Show all posts

Friday, August 29, 2008

Writing clear error messages

Error messages cause our users frustration –and cost us localization dollars to boot. When a user sees the message they’re already frustrated.

Error messages cause our users frustration –and cost us localization dollars to boot. When a user sees the message they’re already frustrated. Whatever they were trying to do didn’t work. Now they see a (sometimes) ambiguous message that isn’t helping:

  • Internal error {1}
  • Array index exception

What’s our style?

The style for Avocent®/LANDesk error messages is:

State the problem. Offer a solution.

I know sometimes I’ve asked the engineers why we’d get to this error in the first place and they don’t know. Sometimes it’s because it’s a relic message; sometimes it’s because we have too many error cases referencing the same message. (In that case we should break it up into more discrete messages.)

All error messages should contain 2 parts:

State the problem. Offer a solution.

This gets the user back on track without leaving them confused about what just happened. So if they’ve typed alphabetic characters in a field expecting numeric characters only, tell them that. This beats just telling them: WRONG! and leaving them to figure it out.

In its basic form, this means: “Invalid value. Type a new value using numeric characters only.”

Tips

Error messages should:

  1. Be written in the user’s language and should be easy to understand.
  2. Be informative but concise. They do not need to include the word “please”.
  3. Be consistent in look and behavior.
  4. Validate all errors on a screen at once. Users should not have to fix a problem, re-select Save or Submit, then receive more error messages.
  5. Be displayed in context when possible, especially in the case of missing or incorrect data in forms. Keeping the user in context helps them fix the problem more quickly.
  6. Not make the user feel stupid or accuse or blame the user. (They’re the ones paying us the money after all.)

What should I look out for?

Spelling and grammar problems

It’s fairly common to see spelling errors, punctuation errors, and style errors such as:

  • Can not for cannot
  • Ocured for occurred
  • Email or E-mail for e-mail
  • web for Web
  • username for user name
  • login for log in (the verb)

These are all things that make us look less-than-professional. Grammatically incorrect sentences make it difficult for everyone to read (and localize). If you need a spell check, copy the string into Word and spell check it there before checking it into the string file in Dev Studio.

Confusing sentences

Some of our technical jargon looks like mush—providing some context can show a localizer it’s not just a string of random words:

“The select statement must contain a where clause.”

to

“The SQL select statement must contain a where clause.”

Unhelpful messages

Sometimes it seems we feel compelled to write short fragments for error messages—even when they are going to pop up into their own message box and there is no real size constraint:

“Invalid character.”

Ok. So I just filled out a dialog box with 5 text boxes and that’s all I get? Tell the user what happened and how to fix it:

“The specified user doesn’t exist. Type a new user name containing only alphanumeric characters.”


Microsoft Vista UX style guidlines

See the Microsoft Vista UX style guidelines for Pike's Peak and later releases.

Mnemonics in dialog boxes

A mnemonic is single key, not used in combination with CTRL, ALT, or SHIFT keys, that activates a menu command in an open menu. A mnemonic is shown as an underlined letter in each menu command.

Mnemonics are discontinued in ALM (Darwin) as current (2008/Vista) Windows style guidelines outline. Keyboard users move the input focus from one control to another in a dialog box with the TAB and ARROW keys.

Mnemonics will continue in LDMS until such a time as HF, Dev, and PM can negotiate their removal in LDMS per the guidelines listed below.

When mnemonics are required:

  • Mnemonics never appear on OK, Cancel or Help buttons. (Or whatever the default buttons are for the Enter and Esc keys such as Save or Close.)
  • MS recommends choosing the mnemonic in the following order of preference:
    • Use the first letter of the command name unless another letter provides a better mnemonic association.
    • If the first letter is already assigned to another command, use a letter that is as close as possible to the first letter of the command name.
    • Use a distinctive consonant in the command name.
    • Use a vowel in the command name.

Sample:

Style guide: LANDesk usage and terminology

LANDesk wording and usage style guidelines follow the following style guidelines in order of precendence:

  1. LANDesk style guidelines
  2. Microsoft Manual of Style
  3. Chicago Manual of Style

In general, theMicrosoft Manual of Style guide covers most terminology and usage issues. Areas where LANDesk differs with that style guide, or that deserve extra attention, are covered below.

Terms



Terminology




Introduction


These terms are listed alphabetically and are marked as follows:

= use this term
= don't use this term; a better one is suggested

Term Description
64-bit, 32-bit, 16-bit Hyphenate when used as an adjective
Alert on LAN No hyphens. Alert on LAN is am IBM trademark term.
AMS² Superscript the "2"
AMT Do not use in most instances. AMT is marketed as Intel(R) VPro(tm). AMT refers to only certain base technologies.
antivirus Do not hyphenate
Autorun One word. Capitalize the "A"
CD Use instead of "disc"
chart Use instead of "graph" when referring to report types. For example, don't use "bar graph," do use "bar chart"
check Use when referring to selecting check boxes. If the check box shouldn't be selected, use "clear"
check box Don't use. Use "option"
clear Use instead of "deselect" (e.g., clear the option)
click Use instead of "select" or "choose" when referring to using menus, buttons, dialog options, and dialog tabs
command line Two words if used as a noun. Hyphenated as an adjective (e.g., command-line option)
computer Use instead of "machine," "PC," or "station"

Use when referring to a combination of Windows NT servers/workstations. Otherwise, use "workstation" or "server"

console Use to refer to the main UI of a product

Don't capitalize. Never use "console" to refer to a computer in general

customer support Use "LANDesk Customer Support." Capitalize each word
deselect Don't use. Use "clear" (e.g., clear the option)
dialog box Use instead of "dialog"

A UI element is a "dialog box" if you can't resize it. A UI element is a "window" if you can resize it, or it has Minimize and Maximize buttons.

dimmed Use instead of "grayed" or "shaded" to describe the appearance of a UI control that's unavailable
disabled Don't use. Use "dimmed" to describe a UI control that's unavailable
drives Don't use a ":" with a drive letter. Instead, use "C drive" or "drive C"
drop-down list Use instead of "pull-down list" or "drop-down list box"
edit box Don't use. Use "field" to describe an area in a dialog that users type or enter information into
e.g. Don't use. Use "for example"
e-mail Hyphenate
enable Use instead of "allow"
etc. Don't use. Use "and so on" or write around: "such as..." and name two examples. In tables, where space may be an issue, you can use "etc."
execute Don't use. Use "run" to describe the action users perform to start an application
file name Two words
floppy disk Don't use. Use "disk"
GB Abbreviation for gigabyte. In text, place a space between the GB and associated number
(e.g., 10 GB)
Gbps Abbreviation for gigabits per second. In text, do not place a space between the Gbps and associated number (e.g., 8Gbps)
GBps Abbreviation for gigabytes per second. In text, do not place a space between the GBps and associated number (e.g., 80GBps)
grayed Don't use. Use "dimmed" to describe a UI control that's unavailable
hard disk Two words. Use instead of "hard drive"
host name Two words
i.e. Don't use. Use "that is" or "such as"
illegal Don't use. Use "invalid" or "unrecognized" + noun. For example, "Invalid command"
Internet Capitalize
intranet Always lowercase
KB Abbreviation for kilobyte. In text, place a space between the KB and associated number
(e.g., 100 KB)
kHz Abbreviation for kilohertz. Use lowercase "k."
launch Don't use. Use "run" to describe the action users perform to start an application
login Use in the context of NetWare servers. Is one word if used as an adjective. "Log in" is two words if used as a verb
logon Use in the context of Windows NT servers. Is one word if used as an adjective. "Log on" is two words if used as a verb. (Log on to the server.)
machine Don't use. Use "device" instead
MB Abbreviation for megabyte. In text, place a space between the MB and associated number
(e.g., 10 MB)
Mbps Abbreviation for megabits per second. In text, do not place a space between the Mbps and associated number (e.g., 100Mbps)
MBps Abbreviation for megabytes per second. In text, do not place a space between the MBps and associated number (e.g., 100MBps)
menu bar Two words. Typically just referred to as a menu.
MHz Abbreviation for megahertz. In text, place a space between the MHz and associated number
(e.g., 450 MHz)
MS-DOS Use "MS-DOS" when specifically referring to the operating system, as in system requirements for one of our products

If using in a generic way, such as "from the DOS prompt, type...", use "DOS" or command prompt.

motherboard For UNIX and Linux, use "baseboard"
network adapter Use instead of "network card"
NT Don't use on its own. Use "Windows NT" instead
online One word
option Use instead of "check box" and "radio button." To describe an action users can perform with an option, use these words: click, check, clear. Or, just use the name of the option: "Click to select Allows USB drives."
pages Use to refer to the dialog boxes of a panel dialog or wizard
paths Use the actual folder capitalization. Don't surround with quotes.

If telling users how to type a UNC path, use this example in lowercase: \\servername\directory

PC In general, don't use. Use "device" instead
please Avoid unless necessary. Instead of saying "Please wait," just let the user know what to expect. "Configuration database. This might take a few minutes."
Plug and Play Uppercase "P's," use "and," no hyphen
press Use to describe the action users perform with keys or a key combination
pre-boot environment Abbreviated as PE as in Linux PE. Environment used as a basis to start a new OS install or to run troubleshooting tools before the full OS boots.
pull-down menu Don't use. Use "menu"
radio button Don't use. Use "option"
real-time Two words. Always hyphenate before a noun.
reinstall One word
rerun Don't use. Use "Run [ProgramName] again"
run Use instead of "execute" or "launch" to describe the action a user must perform to start an application
select Use "click" when possible, but when "click" is ambiguous or when there's a choice users must make among several dialog options, use "select."
Setup One word if used as a noun or adjective. Capitalize when referring to a specific program’s Setup process
set up Two words if used as a verb. "Click Install now to set up the application."
shaded Don't use. Use "dimmed" to describe a UI control that's unavailable
taskbar One word
technical support Don't use. Use "LANDesk Customer Support"; capitalize each word
terminate Don't use. Use "cancel" or "end" instead
that is Use instead of "i.e."
toolbar One word
ToolTip One word; capitalize both Ts
uninstall One word. Use instead of "de-install"
uppercase One word
user name Two words
VPro Formerly known as AMT. AMT now only refers to certain base technologies. VPro should always be accompanied be accompanied by Intel VPro. The approved Intel noun is "technology."
Wake on LAN technology No hyphens. Is a trademark of IBM; always follow with the word "technology." If you refer to it, add this statement to the trademark page of your document:

*Wake on LAN is a trademark of IBM Corporation.

Web site Two words; capitalize "Web"
webmaster Lowercase, one word
Windows operating systems Do not abbreviate. Always spell out the entire name: Windows 95/98, Windows NT, Windows 2000, Windows XP, Windows Vista

To properly trademark: Windows* 95/98, Windows NT*, Windows* 2000

In documentation, after the first occurrence, it's OK to refer to both Windows 95 and Windows 98 as "Windows 95/98." It's also OK after the first occurrence to refer to both Windows NT and Windows 2000 as "Windows NT/2000"

wizard Use instead of "dialog box" when writing about a wizard

Each dialog box of a wizard is called a "page" Most "wizards" are replaced with panel manager dialogs in ver. 8 + product releases.

World Wide Web Capitalize each word. If using just "Web," capitalize. Don't use "Net"

See also: