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 Section 7.5 ― 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 Section A.4 ― 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.