summaryrefslogtreecommitdiff
path: root/doc/development/documentation/styleguide/word_list.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/development/documentation/styleguide/word_list.md')
-rw-r--r--doc/development/documentation/styleguide/word_list.md74
1 files changed, 69 insertions, 5 deletions
diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md
index 65f6a0a328b..e7d927de2cf 100644
--- a/doc/development/documentation/styleguide/word_list.md
+++ b/doc/development/documentation/styleguide/word_list.md
@@ -164,7 +164,15 @@ Use lowercase for **boards**, **issue boards**, and **epic boards**.
Use **text box** to refer to the UI field. Do not use **field** or **box**. For example:
-- In the **Variable name** text box, enter `my text`.
+- In the **Variable name** text box, enter a value.
+
+
+## bullet
+
+Don't refer to individual items in an ordered or unordered list as **bullets**. Use **list item** instead. If you need to be less ambiguous, you can use:
+
+- **Ordered list item** for items in an ordered list.
+- **Unordered list item** for items in an unordered list.
## button
@@ -318,7 +326,22 @@ Use **active** or **on** instead. ([Vale](../testing.md#vale) rule: [`InclusionA
## enter
-Use **enter** instead of **type** when talking about putting values into text boxes.
+In most cases, use **enter** rather than **type**.
+
+- **Enter** encompasses multiple ways to enter information, including speech and keyboard.
+- **Enter** assumes that the user puts a value in a field and then moves the cursor outside the field (or presses <kbd>Enter</kbd>).
+ **Enter** includes both the entering of the content and the action to validate the content.
+
+For example:
+
+- In the **Variable name** text box, enter a value.
+- In the **Variable name** text box, enter `my text`.
+
+When you use **Enter** to refer to the key on a keyboard, use the HTML `<kbd>` tag:
+
+- To view the list of results, press <kbd>Enter</kbd>.
+
+See also [**type**](#type).
## epic
@@ -356,7 +379,7 @@ Use **box** instead of **field** or **text box**.
Use:
-- In the **Variable name** box, enter `my text`.
+- In the **Variable name** text box, enter `my text`.
Instead of:
@@ -392,6 +415,13 @@ Do not make **GitLab** possessive (GitLab's). This guidance follows [GitLab Trad
**GitLab.com** refers to the GitLab instance managed by GitLab itself.
+## GitLab Flavored Markdown
+
+When possible, spell out [**GitLab Flavored Markdown**](../../../user/markdown.md).
+([Vale](../testing.md#vale) rule: [`GLFM.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml))
+
+If you must abbreviate, do not use **GFM**. Use **GLFM** instead.
+
## GitLab SaaS
**GitLab SaaS** refers to the product license that provides access to GitLab.com. It does not refer to the
@@ -518,6 +548,25 @@ Instead of:
Do not use **list** when referring to a [**dropdown list**](#dropdown-list).
Use the full phrase **dropdown list** instead.
+## license
+
+When writing about licenses:
+
+- Do not use variations such as **cloud license**, **offline license**, or **legacy license**.
+- Do not use interchangeably with **subscription**:
+ - A license grants users access to the subscription they purchased, and contains information such as the number of seats they purchased and subscription dates.
+ - A subscription is the subscription tier that the user purchases.
+
+Use:
+
+ - Add a license to your instance.
+ - Purchase a subscription.
+
+Instead of:
+
+ - Buy a license.
+ - Purchase a license.
+
## log in, log on
Do not use **log in** or **log on**. Use [sign in](#sign-in) instead. If the user interface has **Log in**, you can use it.
@@ -576,6 +625,11 @@ Use lowercase for **merge requests**. If you use **MR** as the acronym, spell it
Use lowercase for **milestones**.
+## n/a, N/A, not applicable
+
+When possible, use **not applicable**. Spelling out the phrase helps non-English speaking users and avoids
+capitalization inconsistencies.
+
## navigate
Do not use **navigate**. Use **go** instead. For example:
@@ -950,7 +1004,17 @@ Use [**2FA** and **two-factor authentication**](#2fa-two-factor-authentication)
## type
-Do not use **type** if you can avoid it. Use **enter** instead.
+Use **type** when the cursor remains in the field you're typing in. For example,
+in a search dialog, you begin typing and the field populates results. You do not
+click out of the field.
+
+For example:
+
+- To view all users named Alex, type `Al`.
+- To view all labels for the documentation team, type `doc`.
+- For a list of quick actions, type `/`.
+
+See also [**enter**](#enter).
## update
@@ -1031,7 +1095,7 @@ Sometimes you might need to use **yet** when writing a task. If you use
**yet**, ensure the surrounding phrases are written
in present tense, active voice.
-[View guidance about how to write about future features](index.md#promising-features-in-future-versions).
+[View guidance about how to write about future features](../versions.md#promising-features-in-future-versions).
([Vale](../testing.md#vale) rule: [`CurrentStatus.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/CurrentStatus.yml))
## you, your, yours