Spelling and grammar

• Use American English spelling, but mostly British English grammar.
• Try to write in a simple, precise and concise manner. Non-native English speakers are likely to be reading the documentation, so it must be easy to understand for as many people as possible.

Objects in the UI

• Button - In general, try to avoid using button to refer to a button unless the button has a label which makes the sentence sound ambiguous. Referring to it as a button is superfluous and make the sentence sound slightly more technical. For example, you would normally say Click Save rather than Click the Save button. However, you would say Click the Links button rather than Click Links because otherwise the sentence would be ambiguous.

• Folder - Never use directory unless it is specifically used as a label in the UI.

• Header bar - The top window bar (which includes the title bar plus might include some buttons) of an application is called header bar.

GNOME Shell UI elements

• Top bar - The black panel running across the top of the screen

• Dash - The vertical bar at the bottom of the activities overview which contains favorite applications.

• Activities overview - The screen which is displayed when you move the mouse to the top-left corner of the screen.

• Search box - The box used for searching for applications in the activities overview.

• Workspace selector - The vertical bar in the top area of the activities overview. The items in the workspace selector are "workspace thumbnails".

• Messages - The notification messages that pop-up at the top of the screen. Do not call them "notifications".

• system status area - The area in the right-hand corner of the top bar which displays status icons.

• system menu- The menu in the right-hand corner of the top bar.

• The application name in the top bar - The window title which appears next to the Activities button on the top bar.

• The icon in the top bar - Used to describe any of the applets/menus in the system status area of the top bar.

Referring to actions

• Click - Use click when the user needs to push a button. Never use push, press, click on, or left-click. Left-handed users will be able to figure out that they need to use the opposite button. Use right-click (including hyphen) when the user needs to click with the right mouse button. Say click with the middle mouse button rather than middle-click. e.g. Click Save and choose a name for the file.

• Press - Use press when the user must press a button on the keyboard. Do not use this term when referring to the mouse. Do not use push. e.g. Press Ctrl + A to select all of the text.

• Open a menu

• Press a button

• Select a menuitem

• Switches - Switch the <blah> switch to on/off.

Devices

• cursor - the place where letters will be inserted when you type. Not: pointer. ()

• pointer - the arrow that moves on the screen when you use a mouse or touchpad. Not: cursor, mouse.

• stylus - a type of physical input device. Not: pen.

Phrases

• Application menu: Open the <app> menu from the top bar and select <menuitem>. (Note: Application menus have been deprecated in GNOME 3.31.)

• Generic window menu: Press the menu button in the top-right corner of the window and select <gui style="menuitem">entryname</gui>.