UI elements and interaction Edit

Note: Highlight: Emphasize on the task to be accomplished, rather than how the user should interact with the UIUI UI is an acronym for User Interface - the layout of the page the user interacts with. Think ‘how are they doing that’ and less about what they are doing. element. Format UI element names in bold, and use appropriate nouns and verbs to describe how to interact with them.

Emphasize the task

When writing about interactions involving the user interface (UI), emphasize on the task to be accomplished, rather than how the user should interact with the UI element. By avoiding reference to UI elements, you help the reader understand the purpose of an instruction and avoid confusion due to additional external elements.

However, be watchful of the context and the reader demographic and how that influences your documentation; sometimes the objective of a procedure is to guide readers through elements on a page.

Examples

Warning: Not recommended: Click the PUBLISH button.


Warning: Not recommended: Click the Publish button.


Warning: Not recommended: Click the “Publish” button.


Tip: Recommended: Click Publish.


Tip: Recommended (consider context): Publish the post.


Warning: Not recommended: Click the arrow indicator to open the Time zone options section.


Tip: Recommended: To open the Time zone options section, click the dropdown arrow.


Tip: Recommended (consider context): Open the Time zone options section.

Top ↑

Formatting UI element names

When referring to a UI element by name, format the name in bold using the <b> element in HTML or ** in Markdown. UI element names include those of buttons, windows, menus, dialogs, or any other element in the page or console that has a visible name. Don’t use code font for UI element names, unless it is an element that requires code font; in which case use both code font and bold text formatting. Capitalize UI element names as per document context, but if the element names are inconsistent, use sentence-case capitalization.

Don’t apply bold formatting to an official feature name or product name, except when it directly refers to an element in the page that uses the name (such as a window title or button name).

Examples

Warning: Not recommended: In the Appearance section, select “Themes” and then click the “Add New” button.


Tip: Recommended: In the Appearance section, select the Themes option and then click Add New.


Warning: Not recommended: Click DOWNLOAD.


Tip: Recommended: Click Download.

Top ↑

Pressing and typing keyboard keys

To express a key or a combination of keys on a keyboard to be pressed by the user, use the <kbd> element. To refer to a keyboard shortcut, use either keyboard shortcut or key combination. To refer to the action of pressing a key or combination, use the verb press. To refer to the action of inputting a key or combination, use the verbs type, enter, or input.

Examples

Tip: Recommended: Press <kbd>Control+K</kbd>.


The text renders as follows:

Tip: Recommended: Press Control+K.

If you’re using non-HTML markup, use monospace text formatting, which is how <kbd> renders. In Markdown, enclose the key name in backticks (`).

To express a key that the user has to type to enter that key’s value as text input, use the <code> element instead of the <kbd> element. For more information, see Code font.

To refer to a keyboard key, use the key’s name. If the key’s name is ambiguous, use the form the KEY_NAME key.

Examples

Tip: Recommended: Press Esc.


Tip: Recommended: Press the Esc key.

Don’t abbreviate the names of modifier keys such as Control, Shift, Command, and Option. Spell out the complete key names and don’t use their symbols. To refer to a key combination that uses a modifier key, use the form MODIFIER_KEY+KEY_NAME.

Examples

Warning: Not recommended: Press Ctrl+T.


Tip: Recommended: Press Control+T.


Warning: Not recommended: Press ⌘+T.


Tip: Recommended: Press Command+T.

In most cases, to accommodate both Windows and Mac users, insert the Mac shortcut in parentheses after the Windows shortcut.

Examples

Warning: Not recommended: To redo, press Ctrl+Y (⌘+Y).


Tip: Recommended: To redo, press Control+Y (or Command+Y on Mac).

To refer to a key or combination that uses the Shift key, use the form MODIFIER_KEY+Shift+KEY_NAME.

Examples

Tip: Recommended: Press Control+Shift+T.


Tip: Recommended: Press Alt+Shift+R.

In general, use uppercase capitalization for character keys.

Spell out the names of characters that could be ambiguous or confusing in a keyboard shortcut, such as comma, hyphen, period, and plus.

Examples

Warning: Not recommended: Press Control++.


Tip: Recommended: Press Control+Plus.

Top ↑

Terminology and usage

There can be multiple elements in a user interface. Emphasize the task and focus on the feature and functionality of the UI element, rather than focusing on the UI element itself.

Examples

Tip: Recommended: Go to Plugins > Installed Plugins.


Tip: Recommended: In the Plugins section, select Installed Plugins.