diff options
Diffstat (limited to 'doc/development/documentation/styleguide')
-rw-r--r-- | doc/development/documentation/styleguide/index.md | 50 | ||||
-rw-r--r-- | doc/development/documentation/styleguide/word_list.md | 44 |
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 |