From 3ffde2a15b604e885292c09255b90ee5cb9176c3 Mon Sep 17 00:00:00 2001 From: Allie Sadler <102604716+aevesdocker@users.noreply.github.com> Date: Thu, 26 Jun 2025 09:49:46 +0100 Subject: [PATCH] contribute improvement (#22920) ## Description Improvements and additions to the UI elements page of our contribute section ## Related issues or tickets ## Reviews - [ ] Technical review - [ ] Editorial review - [ ] Product review --- _vale/Docker/Acronyms.yml | 1 + _vale/config/vocabularies/Docker/accept.txt | 1 + content/contribute/ui.md | 78 ++++++++++++++------- 3 files changed, 55 insertions(+), 25 deletions(-) diff --git a/_vale/Docker/Acronyms.yml b/_vale/Docker/Acronyms.yml index 7f0fb04110..3d8eb1e867 100644 --- a/_vale/Docker/Acronyms.yml +++ b/_vale/Docker/Acronyms.yml @@ -146,6 +146,7 @@ exceptions: - TTY - TXT - UDP + - UI - URI - URL - USB diff --git a/_vale/config/vocabularies/Docker/accept.txt b/_vale/config/vocabularies/Docker/accept.txt index 8cf40e7801..dc57808c91 100644 --- a/_vale/config/vocabularies/Docker/accept.txt +++ b/_vale/config/vocabularies/Docker/accept.txt @@ -133,6 +133,7 @@ rootful runc Ryuk S3 +scrollable Slack snapshotters? Snyk diff --git a/content/contribute/ui.md b/content/contribute/ui.md index d2b72144ed..c83efd458a 100644 --- a/content/contribute/ui.md +++ b/content/contribute/ui.md @@ -1,45 +1,73 @@ --- title: UI elements in content -description: How to refer and interact with UI content -keywords: ui, contribute, style guide +description: How to refer to and write about UI elements in technical documentation. +keywords: ui, contribute, style guide, docker docs weight: 40 --- -This page contains information on how to write technical content that involves a user interface (UI). +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. -## Format names of UI elements +## Format UI element names -Always bold UI elements when referring to them by name. +Use bold formatting for the visible names of UI elements: -This includes names for buttons, menus, dialogs, windows, list items, or any other feature on the page that has a visible name. +- Buttons +- Dialogs +- Windows +- Tabs +- Menu items +- List items +- Form labels +- Section headings -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. +For example: -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. +*Select **Create**, then fill out the **Name** field.* -## Focus on the task +Do not bold product names or features unless they appear exactly as a label in the UI. -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. +### Capitalization -|Correct |Incorrect | -|:-----------|:------------| -|Expand the **Advanced options** section | Select the zippy to expand the **Advanced options** section| +- Follow the capitalization as it appears in the UI. +- If UI labels are all uppercase or inconsistent, use sentence case in your docs for readability. + +## Write task-focused instructions + +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. + +| Do this | Avoid this | +|----------------------------------|-------------------------------------------| +| Expand the **Advanced options** section. | Select the zippy to expand the **Advanced options** section. | +| Choose a base image for your container. | Select a dropdown and pick something. | -## Refer to UI elements +## Use correct prepositions with UI elements -Don't use UI elements as if they were English verbs or nouns. +Choose the right preposition based on the type of UI element you're referencing. -|Correct |Incorrect | -|:-----------|:------------| -|In the **Name** field, enter an account name. | **Name** the account.| -|To save the settings, select **Save**.| **Save** the settings.| +| Preposition | Use with... | Example | +|-------------|--------------------------------|---------| +| **in** | dialogs, fields, lists, menus, panes, windows | In the **Name** field, enter your project name. | +| **on** | pages, tabs, toolbars | On the **Settings** tab, select **General**. | -## Prepositions -When documenting the UI, use the following prepositions. +## Use consistent UI element terms -|Preposition |UI element | Example | -|:-----------|:------------|:-----------| -|in | dialogs
fields
lists
menus
panes
windows
| In the **Alert** dialog, select **OK**.
In the **Name** field, enter `wsfc-1`.
In the **Item** list, select **Desktop**.
In the **File** menu, click **Tools**.
In the **Metrics** pane, select **New**.
In the **Task** window, select **Start**. | -| on |pages
tabs
toolbars | On the **Create an instance** page, select **Add**.
On the **Edit** tab, select **Save**.
On the **Dashboard toolbar**, select **Edit**.
| +Use these standard terms when referring to elements in Docker products: + +| Preferred Term | Use When Referring To... | +|---------------------|----------------------------------------------| +| **button** | A clickable action element (e.g., **Start**) | +| **field** | A place to enter text or select a value | +| **menu** / **menu item** | A drop-down or navigation option | +| **drop-down** | A drop-down menu item | +| **context switcher** | Specific to toggling on cloud mode | +| **tab** | A selectable view within a window or page | +| **dialog** | A popup window for confirmations or options | +| **section** | A logical grouping of content on a page | +| **list** / **list item** | A scrollable list of selectable entries | +| **toggle** | A binary control (on/off) | +| **checkbox** | A multi-select control | +| **tooltip** | Text that appears on hover | + +Finally, instead of saying “click the control,” say “select the **Create** button.”