UI elements and interaction
Instead of focusing on the widgets and gestures, it is better to state instructions in terms of what the user should accomplish. This approach helps the user understand the purpose of the instruction and future-proof procedures by avoiding reference to UI elements.
It's important to consider the audience and context when creating procedures. Sometimes, the goal may be to help readers navigate through various elements on a page.
| ❌ Not recommended | 👍 Recommended |
|---|---|
| Click the REFRESH button. | Click Refresh. |
| Click the zippy to expand the Advanced options section. | To expand the Advanced options section, click the ➡️ expander arrow. |
Format names of UI elements
When mentioning the name of any UI elements like buttons, menus, dialogs, windows, list items, or any other feature on the page that is visible, use bold text. You can use the <b> element in HTML or ** in Markdown. Avoid using code font unless it meets the requirements for code font. If it does, use both code font and bold.
Use sentence case and appropriate formatting and terminology for all labels:
| ❌ Not recommended | 👍 Recommended |
|---|---|
| In the New Project window, select the New Activity checkbox, and then click Next. | In the New Project window, select New Activity, and then click the Next button. |
When referring to multiple labels that are inconsistently cased, use sentence case for all of the labels.
| ❌ Not recommended | 👍 Recommended |
|---|---|
| Click NEW PROJECT, and then click New Activity. | Click New project, and then click New activity. |
How to refer to UI elements
Don't use UI elements as if they were English verbs or nouns.
| ❌ Not recommended | 👍 Recommended |
|---|---|
| Name the account. | In the Name field, enter an account name. |
| Save the settings. | To save the settings, click Save. |
| Specify a Service account ID. | In the Service account ID field, enter a name. |
Terminology and usage
Focus on the feature and its function, not the specific UI element. Mention the element's name only if it clarifies for the reader.
| 👍 Recommended |
|---|
| Go to File > Tools. |
| In the File menu, click Tools. |