A graphical user interface (GUI) provides the user with a visual way of interacting with a computer and its applications. The main purpose of a GUI is to make the activities that are involved in doing a task simple and quick. Common GUIs require a person to use a mouse or some other pointing and selecting device. GUIs are typically built around windows and menus, which provide a simple means of manipulating files and directories.
The term “graphical user interface” also includes web browsers.
This chapter discusses the following topics:
“Using GUI Terminology” on page 221
“Writing About Windows, Dialog Boxes, and Menus” on page 225
“Writing About the Web” on page 228
Most computer users today are familiar with GUIs. However, you might still need to explain to novice computer users the basic concepts of the GUI and how to work in it.
Once you have established how to work in a GUI, write about the task the user wants to accomplish. You need not describe the detailed steps required to initiate the task. For example, a user rarely chooses menu items or clicks buttons with the goal of displaying other menus or dialog boxes. Rather, users want to accomplish a task that is activated by the menu item or button.
When writing about GUIs, follow these guidelines:
In the preface, define terms that you use throughout your document, such as “point,” “click,” “double-click,” “select,” or “choose.”
You also might provide an illustration of a typical window to clarify terms.
Provide only the essential details or information that the user needs to know to accomplish the task.
Distinguish windows, dialog boxes, and menus with their proper names. Avoid repeated use of the same name when the meaning is clear.
For example, say you have told the user to choose Print from the File menu and the Print window is displayed. You do not need to keep saying “in the Print window” if that is the window in which you want the user to work.
Document field names and menu option names as they appear in the GUI.
You may add initial capital letters even if the word is not capitalized in the interface only to increase the readability of running text.
Incorrect: Select Prompt for credentials for every server for maximum security.
Correct: Select Prompt for Credentials for Every Server for maximum security.
Do not use special text formatting such as an alternative font or bold type for GUI element names such as menu names, menu options, or field names. In documents with a large number of GUI procedures, such text formatting can be distracting and confusing for the reader.
Do not include a colon or ellipsis points associated with a field name or menu option when mentioning the item in running text.
Mention certain technical GUI distinctions only when necessary.
For example, mention that a menu is a pop-up menu or a message is a status message only if that information is germane to the task at hand. This usage might be appropriate if you have multiple types of menus with similar names, for example.
When writing about a mouse, follow these guidelines:
The plural for “mouse” is “mouse devices.”
The buttons on the mouse are referred to as mouse buttons to avoid confusion with control or command buttons in application windows.
Click mouse button 3 in an empty part of the workspace.
Click the right mouse button and drag across the object.
The indicator that shows where the mouse action occurs is called the pointer or cursor.
Keep the user’s attention focused on the screen by writing about the pointer, not the mouse.
Incorrect: Drag the mouse so that the cursor is on a corner of the object.
Correct: Place the cursor on a corner of the object.
When writing about GUIs, reserve certain verbs for specific activities. The following table lists common usages. The terminology of your GUI might require alternatives.
Table 12-1. GUI Verbs
Verb | Action | Example |
|---|---|---|
Choose | To open a menu or initiate a command. | Choose New from the File menu. Save your file, then choose Print. |
Click | To press and release a mouse button without moving the pointer. | Click the left mouse button. Click the OK button. |
Close | To close a window. Synonym for “dismiss.” | Close the Add Users window. |
Copy | To place a duplicate of the selection on the clipboard. | Copy the first figure in Appendix B. |
Cut | To remove the selection from the current location and place it on the clipboard. | Cut the second entry in the list. |
Dismiss | To close a window. | Dismiss the Add Users window. |
Double-click | To click a mouse button twice quickly without moving the pointer. | Double-click the File Manager icon to open the program. |
Drag | To move the pointer or an object by sliding the mouse with one or more buttons pressed. | Drag the pointer to draw a text box. Drag the icon to the upper left corner of the screen. |
Highlight | Use “highlight” as the noun or adjective describing the appearance of selected text or an active button. Use “select” or “emphasize” as the verb form. | The selected text is highlighted. You can display the highlight in color. |
Move | To move the pointer on the workspace by sliding the mouse with no buttons pressed. | Move the pointer outside the Mail window. |
Open | To start or activate an application, or to access a document, file, or folder. To open an application window or web browser window. | Open FrameMaker. Open the Samples document. Open the Add Accounts window. |
Paste | To place the clipboard contents at the insertion point. | Paste the figure into Chapter 3. |
Point | To move the pointer to a specific location on the screen by moving the mouse with no buttons pressed. After the user is familiar with mouse techniques, you do not have to use this term. You can simply write “Click the Trash icon.” | Point to the Trash icon and click to select it. |
Press | To push a mouse button down and hold it down. Do not say “press and hold down,” since the action of pressing includes holding down the button. | Press mouse button 3 on the File button. |
Release | To let up on a mouse button to initiate an action. | Release mouse button 3 when the Print submenu appears. |
Select | To highlight an entire window or data in a window, or to pick something from a list. To describe picking something from a menu, use “choose.” Use “select” as the verb and “highlight” as the noun. | Select the Compose window. Select the second sentence. Select the file name in the list. |
Size | To enlarge or reduce the size of a window. | Size the Text Editor window so that you can display more characters per line. |
A graphical user interface includes the basic elements in which the application displays text and the user interacts with the application: windows, window controls, dialog boxes, and menus.
For examples of how to write procedures for GUI applications, see Chapter 6.
A window is the primary, rectangular area in which application elements are displayed.
The elements in a window vary from application to application. The names of window elements appear in the document’s default font. The following table describes some common window elements.
Table 12-2. Window Elements
Element | Description |
|---|---|
Background | Bordered rectangle in which the application displays its data or the user enters data |
Control area | Region where controls, such as buttons or settings, are displayed |
Footer | Region in which the application displays status and error messages, or state and mode information |
Header or title bar | Region in which the application displays a title as a long-term message |
Icon | Pictorial representation of a base window |
Pop-up window or secondary window | Window that provides related or secondary information |
Controls in windows enable the user to perform actions. The names of controls appear in the document’s default font. For controls such as sliders, radio buttons, and check boxes, name the control type only when you need to distinguish it specifically. Some common window controls are described in the following table.
Table 12-3. CommonWindow Controls
Control | Description | Example |
|---|---|---|
Button | Small area within the main window on which the user clicks to execute commands (command button), display pop-up windows (window button), or display menus (menu button). | Click the OK button. |
Check box (some interfaces use “checkbox”) | A yes or no, or on or off, control. When a setting is selected, a visual indicator appears in the square check box. | Select the No Markers check box. |
Gauge | A read-only control, usually at the bottom of a window, that shows the percentage of use or the portion of an action that has been completed. | The gauge in the status bar shows the progress of the document composition. |
Radio button | A yes or no, or on or off, control. Usually, only one radio button in a group can be selected. | Select the Add User option. |
Resize corner | Control that enables the user to size the window without changing the scale of the contents. | Drag the resize corner to change the size of the window. |
Scrollbar | Control that moves the view of the data that is displayed in the window. | Scroll to the top of your document. |
Slider | Control that is used to set a value within a range and to give a visual indication of the setting. | Drag the slider to the desired saturation value. |
Text field | Input area for text. If the field name includes a trailing colon, do not include the colon when referring to the field in running text. Text field names do not generally appear in an alternate font. Use monospace font for any specific text that you are instructing the user to type into a field. | Type your company name in the Organization field. |
A dialog box is a pop-up window in which the user provides information or issues commands. (In some GUI applications, a dialog box is called a secondary window.) Keep in mind that a user does not select menu items or buttons “to display the dialog box” but to do a task through the dialog box.
Incorrect:
Choose Add Users from the Actions menu to display the Add Users dialog box.
Correct:
Choose Add Users from the Actions menu.
The Add Users dialog box appears.
A menu or a submenu is a list of application options.
If you are writing for novice users who might be unfamiliar with GUIs, use step-by-step instructions when you first write about choosing items or settings from a menu.
Menu option names appear in the document’s default font and do not receive any special typographic styling. Also, even if a menu option includes ellipsis points in the GUI, do not include the ellipsis points when mentioning the option in text.
Here is an example of detailed steps that use menu options.
To paste text:
1. Press mouse button 1 on the Edit button in the menu bar.
The Edit menu is displayed.
2. Drag the pointer to the Paste item and release the mouse button.
The contents of the clipboard are placed at the insertion point.
After you have explained how menus work, streamline the process by saying “Choose Paste from the Edit menu” or “From the Edit menu, choose Paste.”
Alternatively, you can use an arrow symbol to show the menu selection. For example, “Choose Edit ⇒ Paste.”
The World Wide Web is a relatively recent medium. No solid consensus has been reached on industry-standard terminology for browsers or navigation. This section provides some guidelines for usage.
Use the following terminology when writing about the web:
Use “web browser” rather than “web browser window” or “browser” when referring generally to web browsers or to the main or first web browser window.
You “start” a web browser and “open” additional web browser windows or web pages.
Start Netscape Navigator™.
Open the Display Users page.
Use the verbs “navigate” or “browse” when referring generally to moving through a web page rather than “explore” or “surf.”
Assume that URL is pronounced “you-are-ell” and use the appropriate related article (“a URL”).
Use a capital “w” when discussing items on the World Wide Web that are accessible through the Internet.
Additional product information might be available at the company’s Web site.
Do not include proprietary information on the public Web site.
Use a lowercase “w” when discussing general web references or an intranet site.
A web browser reads HTML pages.
The design of your web site should help readers find what they need.
The
hr.centralweb site contains useful employee information.
Use monospace font for URLs.
For information about legal requirements for linking to a third-party Web site, see “Third-Party Web Site References” on page 162. For guidance on writing links, see Chapter 5. For information about referring to online articles or journals, see “Citing Electronic Sources” on page 52.
When introducing URLs, both internal and external, follow these guidelines:
Make references to URLs as simple and direct as possible.
Readers no longer need to be told to type a URL. For example, you do not need to write detailed instructions such as “Point your web browser at the following URL.”
Incorrect:
You can find further information by typing the following URL:
http://www.plirg.com.Correct:
Further information is available at
http://www.plirg.com.Incorrect:
Open the following URL in your web browser:
http://www.plirg.com.Correct:
Go to
http://www.plirg.com.
Precede a URL with “at” or “to” when a preposition is needed.
Incorrect:
Check for updates on
http://www.plirg.com.Correct:
Check for updates at
http://www.plirg.com.Correct:
To check for updates, go to
http://www.plirg.com.
Provide explanatory text about the web site before giving the URL.
A URL is acceptable at the end of a sentence. Readers no longer confuse end punctuation with spelled-out URLs.
Incorrect:
Go to
http://www.plirg.comfor resources for developers and service providers.Correct:
For resources for developers and service providers, go to
http://www.plirg.com.Correct:
PlirgSoft offers resources for developers and service providers at
http://www.plirg.com.
When placing URLs in text, use the following guidelines:
If the URL is long, place the URL on its own line and introduce it with a colon.
If the URL is short, weave it into the sentence.
If your document provides two or more URLs in the same paragraph, place them in a bulleted list.
If you need to refer to an extremely long URL, use one of the following techniques:
Provide the base URL and an indication of what links to click to get to the specific page.
Awkward:
For more legal information, see:
http://plirglegal.north/Legal_Ops/plirglegalweb/legal_orgchart.html.Clearer:
Click Organization Chart on the main Legal web site at
http://plirglegal.north.
Substitute text for the URL in print and use the same text online as a link.