Chapter 11. Language

Table of Contents

Labels
Controls
Tooltips
Menus
Warning and Error Messages
Online Help

Consistent labelling creates a familiar environment that the user can navigate comfortably. The more familiar the environment, the easier task of finding information.

Labels

Controls

Clear, consistent and concise labelling of controls helps users to work out the purpose of a window or dialog they have never seen before. To a visually-impaired user, clear labels are even more important. A user who relies on a screenreader has no assistance from icons, layout, or spacing to work out what the controls do, so clear labelling is essential.

Guidelines

  • Keep labels short. This:

    • Reduces the expansion of text when translated, and thus minimizes the effort required to localize the UI. Translated English text can expand up to 30% in some languages.

    • Facilitates the use of translation engines.

    • Improves speed of comprehension for the user.

    Do not shorten your labels to the point of losing meaning, however. A three-word label that provides clear information is better than a one-word label that is ambiguous or vague. Try to find the fewest possible words to satisfactorily convey the meaning of your label.

  • Do not include text in windows that describes how to use the interface, for example You can install a new theme by dropping it here. As well as adding visual clutter, descriptive labels can also conflict with information provided in documentation.

  • Use standard terms. You can find a list of standard user interface terms in the GNOME Documentation Style Guide, Recommended Terminology..

  • Apply standard capitalization rules. See the section called “Capitalization” for guidelines about capitalization of user interface labels

Tooltips

Toolbar Tooltips

A toolbar tooltip is the short description of a toolbar control's functionality that the user sees when they mouse over it.

Guidelines

  • Concisely state the purpose of the control. The tooltip should be more descriptive than the corresponding menu item name, if there is one, but not verbose. For example, Undo last action for the Undo button.

  • Use sentence capitalization rules. See the section called “Capitalization”.

Application Tooltips

An application tooltip is the short description of your application that the user sees when they mouse over the launcher or menu item for your application. It is stored in the comment field of your application's desktop file. See the section called “Menu Item Tooltips”

Guidelines

  • Create short tooltips. Aim to accurately communicate the functionality of an element with the fewest words possible.

  • Use sentence capitalization rules. See the section called “Capitalization”.

  • Use standard punctuation rules, with the exception that you do not use a period to end the tooltip.

Menus

Guidelines

Warning and Error Messages

A good warning or error message contains two elements:

  1. A brief description of the problem.

  2. A list of ways the user can remedy the problem.

Both of these elements should be presented in non-technical, jargon-free language, unless your target audience is particularly technically-minded.

If your application knows enough about the problem to be able to give all this information to the user, it will often be capable of rectifying the problem itself when the user has decided which course of action they want to take. For example, if the problem is insufficient memory, tell the user which currently-running application is taking up the most memory, and provide a button to close it for them. (Do not offer to launch a graphical process manager, however, which is something most users should never see!)

See the section called “Alerts” for more detailed information on writing and presenting errors, warnings and information alerts.

Online Help

Writing online help is a specialized task, and is therefore not covered in any depth here. Refer to the GNOME Documentation Styleguide for guidance on writing clear, consistent and helpful documentation for your application.