Merge branch 'selhorn-okr-guidelines-for-nav' into 'master'

Updates to nav and SVG guidance

See merge request gitlab-org/gitlab!68699

doc/development/documentation/styleguide/index.md

@@ -1003,9 +1003,23 @@ document to ensure it links to the most recent version of the file.
 
 ## Navigation
 
-When documenting navigation through the user interface, use these terms and styles.
-
-### What to call the menus
+When documenting how to navigate through the GitLab UI:
+
+- Always use location, then action.
+  - `From the **Visibility** list,` (location) `select **Public**.` (action)
+- Be brief and specific. For example:
+  - Avoid: `Select **Save** for the changes to take effect.`
+  - Use instead: `Select **Save**.`
+- When selecting from high-level UI elements, use the word **on**.
+  - Avoid: `From the left sidebar...` or `In the left sidebar...`
+  - Use instead: `On the left sidebar...`
+- If a step must include a reason, start the step with it.
+  - Avoid: `Select the link in the merge request to view the changes.`
+  - Use instead: `To view the changes, select the link in the merge request.`
+- If a step is optional, start the step with the word `Optional` followed by a period.
+  - `1. Optional. Enter a name for the dog.`
+
+### Names for menus
 
 Use these terms when referring to the main GitLab user interface
 elements:
@@ -1017,9 +1031,14 @@ elements:
 - **Right sidebar**: This is the navigation sidebar on the right of the user
   interface, specific to the open issue, merge request, or epic.
 
-### How to document the menus
+### Names for UI elements
+
+UI elements, like button and checkbox names, should be **bold**.
+Guidance for each individual UI element is in [the word list](word_list.md).
+
+### How to write navigation task steps
 
-To be consistent, use this format when you write about UI navigation.
+To be consistent, use this format when you write navigation steps in a task topic.
 
 1. On the top bar, select **Menu > Projects** and find your project.
 1. On the left sidebar, select **Settings > CI/CD**.
@@ -1034,12 +1053,14 @@ Another example:
 An Admin Area example:
 
 ```markdown
-1. On the top bar, select **Menu >** **{admin}** **Admin**.
+1. On the top bar, select **Menu > Admin**.
 ```
 
-This text renders this output:
+To select your avatar:
 
-1. On the top bar, select **Menu >** **{admin}** **Admin**.
+```markdown
+1. On the top bar, in the top right corner, select your avatar.
+```
 
 ## Images
 
@@ -1288,64 +1309,22 @@ For a complete reference on code blocks, see the [Kramdown guide](https://about.
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/384) in GitLab 12.7.
 
 You can use icons from the [GitLab SVG library](https://gitlab-org.gitlab.io/gitlab-svgs/)
-directly in the documentation.
-
-This way, you can achieve a consistent look when writing about interacting with
-GitLab user interface elements.
-
-Usage examples:
-
-- Icon with default size (16px): `**{icon-name}**`
-
-  Example: `**{tanuki}**` renders as: **{tanuki}**.
-- Icon with custom size: `**{icon-name, size}**`
-
-  Available sizes (in pixels): 8, 10, 12, 14, 16, 18, 24, 32, 48, and 72
-
-  Example: `**{tanuki, 24}**` renders as: **{tanuki, 24}**.
-- Icon with custom size and class: `**{icon-name, size, class-name}**`.
+directly in the documentation. For example, `**{tanuki}**` renders as: **{tanuki}**.
 
-  You can access any class available to this element in GitLab documentation CSS.
+In most cases, you should avoid using the icons in text.
+However, you can use an icon when hover text is the only
+available way to describe a UI element. For example, **Delete** or **Edit** buttons
+often have hover text only.
 
-  Example with `float-right`, a
-  [Bootstrap utility class](https://getbootstrap.com/docs/4.4/utilities/float/):
-  `**{tanuki, 32, float-right}**` renders as: **{tanuki, 32, float-right}**
-
-### When to use icons
-
-Icons should be used sparingly, and only in ways that aid and do not hinder the
-readability of the text.
-
-For example, this Markdown adds little to the accompanying text:
-
-```markdown
-1. Go to **{home}** **Project information > Details**.
-```
-
-1. Go to **{home}** **Project information > Details**.
-
-However, these tables might help the reader connect the text to the user
-interface:
-
-```markdown
-| Section                  | Description                                                                                                                 |
-|:-------------------------|:----------------------------------------------------------------------------------------------------------------------------|
-| **{overview}** Overview  | View your GitLab Dashboard, and administer projects, users, groups, jobs, runners, and Gitaly servers.                      |
-| **{monitor}** Monitoring | View GitLab system information, and information on background jobs, logs, health checks, requests profiles, and audit events. |
-| **{messages}** Messages  | Send and manage broadcast messages for your users.                                                                          |
-```
+When you do use an icon, start with the hover text and follow it with the SVG reference in parentheses.
 
-| Section                  | Description                                                                                                                 |
-|:-------------------------|:----------------------------------------------------------------------------------------------------------------------------|
-| **{overview}** Overview  | View your GitLab Dashboard, and administer projects, users, groups, jobs, runners, and Gitaly servers.                      |
-| **{monitor}** Monitoring | View GitLab system information, and information on background jobs, logs, health checks, requests profiles, and audit events. |
-| **{messages}** Messages  | Send and manage broadcast messages for your users.                                                                          |
+- Avoid: `Select **{pencil}** **Edit**.` This generates as: Select **{pencil}** **Edit**.
+- Use instead: `Select **Edit** (**{pencil}**).` This generates as: Select **Edit** (**{pencil}**).
 
-Use an icon when you find yourself having to describe an interface element. For
-example:
+Do not use words to describe the icon:
 
-- Do: Select the Admin Area icon ( **{admin}** ).
-- Don't: Select the Admin Area icon (the wrench icon).
+- Avoid: `Select **Erase job log** (the trash icon).`
+- Use instead: `Select **Erase job log** (**{remove}**).` This generates as: Select **Erase job log** (**{remove}**).
 
 ## Alert boxes
 

doc/development/documentation/styleguide/word_list.md

@@ -52,6 +52,10 @@ in the handbook when writing about Alpha features.
 
 Instead of **and/or**, use or or rewrite the sentence to spell out both options.
 
+## area
+
+Use [section](#section) instead. The only exception is [the Admin Area](#admin-admin-area).
+
 ## below
 
 Try to avoid extra words when referring to an example or table in a documentation page, but if required, use **following** instead.
@@ -71,6 +75,19 @@ Do not use. Another option is **denylist**. ([Vale](../testing.md#vale) rule: [`
 
 Use lowercase for **boards**, **issue boards**, and **epic boards**.
 
+## box
+
+Use instead of **field** or **text box**. For example:
+
+- In the **Variable name** box, enter `my text`.
+
+## button
+
+Don't use a descriptor.
+
+- Avoid: Select the **Run pipelines** button.
+- Use instead: Select **Run pipelines**.
+
 ## checkbox
 
 One word, **checkbox**. Do not use **check box**.
@@ -86,6 +103,16 @@ Always uppercase. No need to spell out on first use.
 Do not use. Instead, use **select** with buttons, links, menu items, and lists.
 **Select** applies to more devices, while **click** is more specific to a mouse.
 
+## collapse
+
+Use instead of **close** when you are talking about expanding or collapsing a section in the UI.
+
+## confirmation dialog
+
+Use to describe the dialog box that asks you to confirm your action. For example:
+
+- From the confirmation dialog, select **OK**.
+
 ## currently
 
 Do not use when talking about the product or its features. The documentation describes the product as it is today. ([Vale](../testing.md#vale) rule: [`CurrentStatus.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/CurrentStatus.yml))
@@ -113,6 +140,15 @@ Do not use **Developer permissions**. A user who is assigned the Developer role
 See [the Microsoft style guide](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/d/disable-disabled) for guidance.
 Use **inactive** or **off** instead. ([Vale](../testing.md#vale) rule: [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml))
 
+## dropdown, dropdown list
+
+Do not use. Use **list** instead.
+
+Include the descriptor when writing about lists. Start with the list name,
+then follow with the item the user should select. For example:
+
+- From the **Visibility** list, select **Public**.
+
 ## earlier
 
 Use when talking about version numbers.
@@ -128,10 +164,6 @@ Do not use. If the user doesn't find the process to be easy, we lose their trust
 
 Do not use Latin abbreviations. Use **for example**, **such as**, **for instance**, or **like** instead. ([Vale](../testing.md#vale) rule: [`LatinTerms.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/LatinTerms.yml))
 
-## expand
-
-Use instead of **open** when you are talking about expanding or collapsing a section in the UI.
-
 ## email
 
 Do not use **e-mail** with a hyphen. When plural, use **emails** or **email messages**.
@@ -156,6 +188,17 @@ Try to avoid. Be as specific as you can. Do not use **and so on** as a replaceme
 - Avoid: You can update objects, like merge requests, issues, etc.
 - Use instead: You can update objects, like merge requests and issues.
 
+## expand
+
+Use instead of **open** when you are talking about expanding or collapsing a section in the UI.
+
+## field
+
+Use **box** instead of **field** or **text box**.
+
+- Avoid: In the **Variable name** field, enter `my text`.
+- Use instead: In the **Variable name** box, enter `my text`.
+
 ## foo
 
 Do not use in product documentation. You can use it in our API and contributor documentation, but try to use a clearer and more meaningful example instead.
@@ -262,6 +305,14 @@ Use when talking about version numbers.
 - Avoid: In GitLab 14.1 and higher.
 - Use instead: In GitLab 14.1 and later.
 
+## list
+
+Use instead of **dropdown**, **drop-down** or **dropdown list**. You select an item from a list. For example:
+
+- From the **Availability** list, select **public**.
+
+The list name, and the items you select, should be bold.
+
 ## log in, log on
 
 Do not use. Use [sign in](#sign-in) instead. If the user interface has **Log in**, you can use it.
@@ -407,6 +458,22 @@ Do not use. Use **check for completeness** instead. ([Vale](../testing.md#vale)
 
 Do not use when talking about increasing GitLab performance for additional users. The words scale or scaling are sometimes acceptable, but references to increasing GitLab performance for additional users should direct readers to the GitLab [reference architectures](../../../administration/reference_architectures/index.md) page.
 
+## section
+
+Use to describe an area on a page. For example, if a page has lines that separate the UI
+into separate areas, refer to these areas as sections.
+
+We often think of expandable/collapsible areas as **sections**. When you refer to expanding
+or collapsing a section, don't include the word **section**.
+
+- Avoid: Expand the **Auto DevOps** section.
+- Use instead: Expand **Auto DevOps**.
+
+## select
+
+Use with buttons, links, menu items, and lists. **Select** applies to more devices,
+while **click** is more specific to a mouse.
+
 ## setup, set up
 
 Use **setup** as a noun, and **set up** as a verb. For example: