Welcome to mirror list, hosted at ThFree Co, Russian Federation.

gitlab.com/gitlab-org/gitlab-foss.git - Unnamed repository; edit this file 'description' to name the repository.
summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat (limited to 'doc/development/documentation/styleguide')
-rw-r--r--doc/development/documentation/styleguide/index.md50
-rw-r--r--doc/development/documentation/styleguide/word_list.md44
2 files changed, 84 insertions, 10 deletions
diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md
index 709e6b2d0d9..bc79bf0fbe2 100644
--- a/doc/development/documentation/styleguide/index.md
+++ b/doc/development/documentation/styleguide/index.md
@@ -887,7 +887,7 @@ To be consistent, use these templates when you write navigation steps in a task
To open project settings:
```markdown
-1. On the top bar, select **Menu > Projects** and find your project.
+1. On the top bar, select **Main menu > Projects** and find your project.
1. On the left sidebar, select **Settings > CI/CD**.
1. Expand **General pipelines**.
```
@@ -895,7 +895,7 @@ To open project settings:
To open group settings:
```markdown
-1. On the top bar, select **Menu > Groups** and find your group.
+1. On the top bar, select **Main menu > Groups** and find your group.
1. On the left sidebar, select **Settings > CI/CD**.
1. Expand **General pipelines**.
```
@@ -903,7 +903,7 @@ To open group settings:
To open the Admin Area:
```markdown
-1. On the top bar, select **Menu > Admin**.
+1. On the top bar, select **Main menu > Admin**.
```
To select your avatar:
@@ -950,7 +950,7 @@ Use the phrase **Complete the fields**.
For example:
-1. On the top bar, select **Menu > Projects** and find your project.
+1. On the top bar, select **Main menu > Projects** and find your project.
1. On the left sidebar, select **Settings > Repository**.
1. Expand **Push rules**.
1. Complete the fields.
@@ -1361,6 +1361,48 @@ It renders on the GitLab documentation site as:
> - This is a list item
> - Second item in the list
+## Tabs
+
+On the docs site, you can format text so it's displayed as tabs.
+
+To create a set of tabs, follow this example:
+
+```plaintext
+::Tabs
+
+:::TabTitle Tab One
+
+Here's some content in tab one.
+
+:::TabTitle Tab Two
+
+Here's some other content in tab two.
+
+::EndTabs
+```
+
+This code renders on the GitLab documentation site as:
+
+::Tabs
+
+:::TabTitle Tab One
+
+Here's some content in tab one.
+
+:::TabTitle Tab Two
+
+Here's some other content in tab two.
+
+::EndTabs
+
+For tab titles, be brief and consistent. Ensure they are parallel, and start each with a capital letter.
+For example:
+
+- `Omnibus package`, `Helm chart`, `Source`
+- `15.1 and earlier`, `15.2 and later`
+
+See [Pajamas](https://design.gitlab.com/components/tabs/#guidelines) for details.
+
## Terms
To maintain consistency through GitLab documentation, use these styles and terms.
diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md
index 1976caefc8e..029c7389290 100644
--- a/doc/development/documentation/styleguide/word_list.md
+++ b/doc/development/documentation/styleguide/word_list.md
@@ -8,8 +8,12 @@ description: 'Writing styles, markup, formatting, and other standards for GitLab
# Recommended word list
To help ensure consistency in the documentation, the Technical Writing team
-recommends these wording choices. The GitLab handbook also maintains a list of
-[top misused terms](https://about.gitlab.com/handbook/communication/top-misused-terms/).
+recommends these word choices. In addition:
+
+- The GitLab handbook contains a list of
+ [top misused terms](https://about.gitlab.com/handbook/communication/top-misused-terms/).
+- The documentation [style guide](../styleguide#language) includes details
+ about language and capitalization.
For guidance not on this page, we defer to these style guides:
@@ -19,6 +23,10 @@ For guidance not on this page, we defer to these style guides:
<!-- vale off -->
<!-- markdownlint-disable -->
+## `&`
+
+Do not use Latin abbreviations. Use **and** instead, unless you are documenting a UI element that uses an `&`.
+
## `@mention`
Try to avoid **`@mention`**. Say **mention** instead, and consider linking to the
@@ -75,7 +83,7 @@ Instead of:
## Admin Area
-Use title case **Admin Area** to refer to the area of the UI that you access when you select **Menu > Admin**.
+Use title case **Admin Area** to refer to the area of the UI that you access when you select **Main menu > Admin**.
This area of the UI says **Admin Area** at the top of the page and on the menu.
## agent
@@ -139,6 +147,18 @@ Do not use **and so on**. Instead, be more specific. For details, see
Use [**section**](#section) instead of **area**. The only exception is [the Admin Area](#admin-area).
+## as
+
+Do not use **as** to mean **because**.
+
+Use:
+
+- Because none of the endpoints return an ID...
+
+Instead of:
+
+- As none of the endpoints return an ID...
+
## associate
Do not use **associate** when describing adding issues to epics, or users to issues, merge requests,
@@ -265,6 +285,13 @@ Use title case for the GitLab Container Registry.
Do not use **currently** 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))
+## default branch
+
+Use **default branch** to refer generically to the primary branch in the repository.
+Users can set the default branch by using a UI setting.
+
+For examples that use the default branch, use `main` instead of [`master`](#master).
+
## Dependency Proxy
Use title case for the GitLab Dependency Proxy.
@@ -394,7 +421,7 @@ Information in FAQs belongs with other similar information, under an easily sear
## field
-Use **box** instead of **field** or **text box**.
+Use **text box** instead of **field** or **box**.
Use:
@@ -407,7 +434,7 @@ Instead of:
However, you can make an exception when you are writing a task and you need to refer to all
of the fields at once. For example:
-1. On the top bar, select **Menu > Projects** and find your project.
+1. On the top bar, select **Main menu > Projects** and find your project.
1. On the left sidebar, select **Settings > CI/CD**.
1. Expand **General pipelines**.
1. Complete the fields.
@@ -604,6 +631,10 @@ Instead of:
- Buy a license.
- Purchase a license.
+## limitations
+
+Do not use **limitations**. Use **known issues** instead.
+
## 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.
@@ -644,7 +675,8 @@ Do not use **manpower**. Use words like **workforce** or **GitLab team members**
## master
-Do not use **master**. Options are **primary** or **main**. ([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml))
+Do not use `master`. Use `main` when you need a sample [default branch name](#default-branch).
+([Vale](../testing.md#vale) rule: [`InclusionCultural.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionCultural.yml))
## may, might