# Writing for GUIs

This chapter provides guidelines about how to document graphical user interfaces (GUIs) in the GNOME Desktop.

## GUI Basics

A graphical user interface (GUI) provides the user with an intuitive way of interacting with a computer and computer applications. The main purpose of a GUI is to make the activities involved in doing a task simple and quick. GUIs include elements that users use to work with applications, and elements that display information to the users.

GNOME documentation must cater for the following GNOME GUIs:

- GNOME Desktop GUI

- Application GUIs

- Applet GUIs

The GNOME Desktop GUI includes the following elements:

- Buttons

- Desktop

- Dialogs

- Menus

- Panels

- Windows

## Writing About GNOME Desktop GUIs

When you write about GNOME Desktop GUIs, observe the following guidelines:

- Provide only the essential details or information that the user needs to know to accomplish a task.

- Refer to windows and dialogs by the title of the window or dialog. Refer to menus by the title of the menu, or by the name specified for the menu in menu-terminology.

  Avoid repeated use of the same name when the meaning is clear. For example: you instruct the reader to choose File Print , with the expected result that the Print window is displayed. In this case, you do not need to repeat "in the Print window", if there is no ambiguity about which window you want the user to work in.

- Write the names of dialog elements and menu commands as they appear in the GUI. If the name includes a colon or an ellipsis, do not include that punctuation when you refer to the item in your documentation.

- Mention certain technical GUI distinctions only when necessary. For example, mention that a menu is a popup menu only if that information is relevant to the task that the documentation describes.

When writing about the GUI, reserve certain verbs for specific activities. For a list of the verbs to use when writing about the GUI, see gnome-glossary-user-actions.

When you write about the mouse, note the following:

- Refer to the buttons on the mouse as mouse buttons to avoid confusion with buttons in dialogs.

- Refer to the indicator that shows where the mouse action occurs as the pointer or mouse pointer. Write about the pointer to keep the user focused on the screen. For example, describe moving the pointer, not moving the mouse.

- The plural for mouse is mouse devices.

## GNOME Desktop Terminology

The following terms are of prime interest when you write about the GNOME Desktop:

- Desktop

- Desktop background

- Desktop environment

- GNOME Desktop

Use the terminology shown in desktop-fig when you write about GNOME Desktop components.

### GNOME Desktop Terminology

GNOME Desktop. Callouts: Panel, Desktop objects, Desktop, Pointer, Panel.

For more detailed information on the terms in desktop-fig, see wordlist.

## Panel Terminology

A panel is an area in the GNOME Desktop from which you can run applications and applets, and perform other tasks. Use the terminology shown in panel-fig when you write about panels.

### Panel Terminology

Horizontal panel with hide buttons and panel objects. Callouts: Hide button, Panel objects, Launcher, Menu, Applet, Drawer, Other panel object.

For more detailed information on the terms in panel-fig, see wordlist.

## Menu Terminology

A menu or a submenu is a list of commands. gui-TBL-4 lists and illustrates some of the menus in GNOME GUIs. Use the terms in gui-TBL-4 when you need to refer to a particular menu.

Note that you do not need to specify the name of a menu when you refer to commands on the menu. For example, you can write "To add an object to a panel, right-click on the panel, then choose Add to Panel".

## Menu Terminology

Menu | Example
Applet popup menu | Sample applet popup menu.
Desktop menu | Desktop menu.
Main Menu | Main Menu.
Menu item popup menu | Sample launcher popup menu.
Panel popup menu | Panel popup menu.
Panel object popup menu | Panel object popup menu.
Window Menu | Window Menu.

For more detailed information on the terms in gui-TBL-4, see wordlist.

## Window Terminology

A window is a rectangular frame that displays a particular application. Typically, applications have one main window from which users can open secondary windows, called dialogs. Use the terminology shown in window-fig-1 when you write about windows.

### Window Terminology

Sample window, with the following callouts: Frame, Window name, Border, Menubar, Handle, Toolbar, Statusbar.

A window frame is a border around a window. You can use the window frame to perform various actions on the window. In particular, the titlebar contains various active control elements. Use the terminology shown in window-fig-2 when you write about window frames and the elements in window frames.

### Window Frame Terminology

Sample window titlebar, with the following callouts: Window Menu button, Titlebar, Minimize button, Maximize button, Close Window button.

A pane is a subdivision of a window. For example, a Nautilus window can contain two panes: a side pane and a view pane. window-fig-3 shows panes in an Evolution Inbox window.

### Window Pane Terminology

Evolution Inbox window, with the following callouts: Folder pane, Message pane, Preview pane.

For more detailed information on window terms, see wordlist.

## Dialog Terminology

A dialog is a popup window in which the user enters information or commands. Dialogs can contain control elements that the user can work with to select an option, specify a value, and so on. gui-TBL-2 lists and illustrates the dialog elements in the GNOME Desktop GUI. Use the terms in gui-TBL-2 when you write about dialog elements.

## Dialog Terminology

Element | Example
Check box | Sample check box.
Color wheel | Sample color wheel. Sample color wheel.
Column heading | Sample column heading.
Drop-down combination box | Sample drop-down combination box.
Drop-down list | Sample drop-down list.
Drop-down section | Sample closed drop-down section. Sample open drop-down section.
Field | Sample field.
Group box | Sample group box.
List box | Sample list box.
Radio button | Sample radio button.
Scrollbar | Sample scrollbar.
Slider | Sample slider.
Spin box | Sample spin box.
Tab | Sample tabs.
Tabbed section | Sample tabbed section.
Table | Sample table.
Text box | Sample text box.

For more detailed information on dialog terms, see gnome-glossary-desktop.

## Button Terminology

gui-TBL-5 lists and illustrates some of the button types that you can use in GNOME Desktop GUIs. Use the terms in gui-TBL-5 when you write about buttons.

## Button Terminology

Button | Example
Arrow buttons | Sample arrow button Sample arrow button
Color selector button | Sample color selector button
Command button | Sample command button
Font selector button | Sample font selector button
Icon selector buttons | Sample icon selector button Sample icon selector button
Main Menu button | Main Menu button
Toggle buttons | Sample toggle buttons
Toolbar buttons | Sample toolbar button
Window frame buttons | Sample window frame buttons
Window list buttons | Sample window list buttons

For more detailed information on GUI buttons, see gnome-glossary-button-types.