Add new styleguide sections for verbs

Also fixes spelling, and makes the Markdown style more consistent.

1 files changed, 31 insertions, 3 deletions

diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md
index 829dcf18926..07e247da5e6 100644
--- a/doc/development/documentation/styleguide.md
+++ b/doc/development/documentation/styleguide.md
@@ -210,7 +210,7 @@ For other punctuation rules, please refer to the
 - Use inline link markdown markup `[Text](https://example.com)`.
   It's easier to read, review, and maintain. **Do not** use `[Text][identifier]`.
 - To link to internal documentation, use relative links, not full URLs. Use `../` to
-  navigate tp high-level directories, and always add the file name `file.md` at the
+  navigate to high-level directories, and always add the file name `file.md` at the
   end of the link with the `.md` extension, not `.html`.
   Example: instead of `[text](../../merge_requests/)`, use
   `[text](../../merge_requests/index.md)` or, `[text](../../ci/README.md)`, or,
@@ -386,8 +386,32 @@ Which renders to:
 
 ## Specific sections and terms
 
-To mention and/or reference specific terms in GitLab, please follow the styles
-below.
+To maintain consistency through GitLab documentation, the following guides documentation authors
+on agreed styles and usage of terms.
+
+### Describing UI elements
+
+The following are styles to follow when describing UI elements on a screen:
+
+- For elements with a visible label, use that label in bold with matching case. For example, `the **Cancel** button`.
+- For elements with a tooltip or hover label, use that label in bold with matching case. For example, `the **Add status emoji** button`.
+
+### Verbs for UI elements
+
+The following are verbs that should be used in preference to alternatives.
+
+| Use      | Used for                        | Do not use                 |
+|:---------|:--------------------------------|:---------------------------|
+| "click"  | buttons, links, menu items      | "hit", "press", "select"   |
+| "check"  | checkboxes                      | "enable", "click", "press" |
+| "select" | dropdowns                       | "pick"                     |
+| "expand" | expandable sections             | "open"                     |
+
+### Other Verbs
+
+| Use      | Used for                        | Do not use                 |
+|:---------|:--------------------------------|:---------------------------|
+| "go"     | making a browser go to location | "navigate", "open"         |
 
 ### GitLab versions and tiers
 
@@ -460,6 +484,10 @@ the special markup `**[STARTER]**` will generate a `span` element to trigger the
 badges and tooltips (`<span class="badge-trigger starter">`). When the keyword
 "only" is added, the corresponding GitLab.com badge will not be displayed.
 
+## Specific sections
+
+Certain styles should be applied to specific sections. Styles for specific sections are outlined below.
+
 ### GitLab Restart
 
 There are many cases that a restart/reconfigure of GitLab is required. To