|
1 | 1 | --- |
2 | 2 | title: UI elements in content |
3 | | -description: How to refer and interact with UI content |
4 | | -keywords: ui, contribute, style guide |
| 3 | +description: How to refer to and write about UI elements in technical documentation. |
| 4 | +keywords: ui, contribute, style guide, docker docs |
5 | 5 | weight: 40 |
6 | 6 | --- |
7 | 7 |
|
8 | | -This page contains information on how to write technical content that involves a user interface (UI). |
| 8 | +Use this guide when writing documentation that refers to buttons, fields, menus, dialogs, or other user interface (UI) elements. It explains how to format UI terms, write task-focused instructions, and refer to common UI patterns consistently and clearly. |
9 | 9 |
|
10 | | -## Format names of UI elements |
| 10 | +## Format UI element names |
11 | 11 |
|
12 | | -Always bold UI elements when referring to them by name. |
| 12 | +Use bold formatting for the visible names of UI elements: |
13 | 13 |
|
14 | | -This includes names for buttons, menus, dialogs, windows, list items, or any other feature on the page that has a visible name. |
| 14 | +- Buttons |
| 15 | +- Dialogs |
| 16 | +- Windows |
| 17 | +- Tabs |
| 18 | +- Menu items |
| 19 | +- List items |
| 20 | +- Form labels |
| 21 | +- Section headings |
15 | 22 |
|
16 | | -Don't make an official feature name or product name bold, except when it directly refers to an element on the page that uses the name, such as a window title or button name. |
| 23 | +For example: |
17 | 24 |
|
18 | | -In most cases, follow the capitalization as it appears on the page. However, if labels are inconsistent or they're all uppercase, use sentence case. |
| 25 | +*Select **Create**, then fill out the **Name** field.* |
19 | 26 |
|
20 | | -## Focus on the task |
| 27 | +Do not bold product names or features unless they appear exactly as a label in the UI. |
21 | 28 |
|
22 | | -When practical, state instructions in terms of what the user should accomplish, rather than focusing on the widgets and gestures. By avoiding reference to UI elements, you help the user understand the purpose of an instruction, and it can help future-proof procedures. |
| 29 | +### Capitalization |
23 | 30 |
|
24 | | -|Correct |Incorrect | |
25 | | -|:-----------|:------------| |
26 | | -|Expand the **Advanced options** section | Select the zippy to expand the **Advanced options** section| |
| 31 | +- Follow the capitalization as it appears in the UI. |
| 32 | +- If UI labels are all uppercase or inconsistent, use sentence case in your docs for readability. |
27 | 33 |
|
| 34 | +## Write task-focused instructions |
28 | 35 |
|
29 | | -## Refer to UI elements |
| 36 | +When possible, guide users based on what they’re trying to do, not just what they should select. This makes docs more goal-oriented and adaptable to UI changes. |
30 | 37 |
|
31 | | -Don't use UI elements as if they were English verbs or nouns. |
| 38 | +| Do this | Avoid this | |
| 39 | +|----------------------------------|-------------------------------------------| |
| 40 | +| Expand the **Advanced options** section. | Select the zippy to expand the **Advanced options** section. | |
| 41 | +| Choose a base image for your container. | Select a dropdown and pick something. | |
32 | 42 |
|
33 | | -|Correct |Incorrect | |
34 | | -|:-----------|:------------| |
35 | | -|In the **Name** field, enter an account name. | **Name** the account.| |
36 | | -|To save the settings, select **Save**.| **Save** the settings.| |
37 | 43 |
|
38 | | -## Prepositions |
| 44 | +## Use correct prepositions with UI elements |
39 | 45 |
|
40 | | -When documenting the UI, use the following prepositions. |
| 46 | +Choose the right preposition based on the type of UI element you're referencing. |
41 | 47 |
|
42 | | -|Preposition |UI element | Example | |
43 | | -|:-----------|:------------|:-----------| |
44 | | -|in | dialogs <br>fields <br>lists <br>menus <br>panes <br>windows <br>| In the **Alert** dialog, select **OK**. <br> In the **Name** field, enter `wsfc-1`. <br> In the **Item** list, select **Desktop**. <br>In the **File** menu, click **Tools**.<br> In the **Metrics** pane, select **New**. <br>In the **Task** window, select **Start**. | |
45 | | -| on |pages <br>tabs <br>toolbars | On the **Create an instance** page, select **Add**. <br> On the **Edit** tab, select **Save**.<br> On the **Dashboard toolbar**, select **Edit**.<br>| |
| 48 | +| Preposition | Use with... | Example | |
| 49 | +|-------------|--------------------------------|---------| |
| 50 | +| **in** | dialogs, fields, lists, menus, panes, windows | In the **Name** field, enter your project name. | |
| 51 | +| **on** | pages, tabs, toolbars | On the **Settings** tab, select **General**. | |
| 52 | + |
| 53 | + |
| 54 | +## Use consistent UI element terms |
| 55 | + |
| 56 | +Use these standard terms when referring to elements in Docker products: |
| 57 | + |
| 58 | +| Preferred Term | Use When Referring To... | |
| 59 | +|---------------------|----------------------------------------------| |
| 60 | +| **button** | A clickable action element (e.g., **Start**) | |
| 61 | +| **field** | A place to enter text or select a value | |
| 62 | +| **menu** / **menu item** | A drop-down or navigation option | |
| 63 | +| **drop-down** | A drop-down menu item | |
| 64 | +| **context switcher** | Specific to toggling on cloud mode | |
| 65 | +| **tab** | A selectable view within a window or page | |
| 66 | +| **dialog** | A popup window for confirmations or options | |
| 67 | +| **section** | A logical grouping of content on a page | |
| 68 | +| **list** / **list item** | A scrollable list of selectable entries | |
| 69 | +| **toggle** | A binary control (on/off) | |
| 70 | +| **checkbox** | A multi-select control | |
| 71 | +| **tooltip** | Text that appears on hover | |
| 72 | + |
| 73 | +Finally, instead of saying “click the control,” say “select the **Create** button.” |
0 commit comments