diff options
Diffstat (limited to 'doc/development/documentation')
| -rw-r--r-- | doc/development/documentation/alpha_beta.md | 2 | ||||
| -rw-r--r-- | doc/development/documentation/contribute.md | 2 | ||||
| -rw-r--r-- | doc/development/documentation/feature_flags.md | 24 | ||||
| -rw-r--r-- | doc/development/documentation/index.md | 2 | ||||
| -rw-r--r-- | doc/development/documentation/restful_api_styleguide.md | 18 | ||||
| -rw-r--r-- | doc/development/documentation/site_architecture/folder_structure.md | 38 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide/index.md | 32 | ||||
| -rw-r--r-- | doc/development/documentation/styleguide/word_list.md | 135 | ||||
| -rw-r--r-- | doc/development/documentation/workflow.md | 2 |
9 files changed, 153 insertions, 102 deletions
diff --git a/doc/development/documentation/alpha_beta.md b/doc/development/documentation/alpha_beta.md index a6f756f93ae..61f07e79e12 100644 --- a/doc/development/documentation/alpha_beta.md +++ b/doc/development/documentation/alpha_beta.md @@ -29,7 +29,7 @@ For example: FLAG: On self-managed GitLab, by default this feature is not available. -To make it available, ask an administrator to enable the feature flag named `example_flag`. +To make it available, an administrator can enable the feature flag named `example_flag`. On GitLab.com, this feature is not available. This feature is not ready for production use. Use this great new feature when you need to do this new thing. diff --git a/doc/development/documentation/contribute.md b/doc/development/documentation/contribute.md index d3b7d9a4d93..b6573665f8d 100644 --- a/doc/development/documentation/contribute.md +++ b/doc/development/documentation/contribute.md @@ -54,7 +54,7 @@ When you are ready to update the documentation: 1. In the **Commit message** text box, enter a commit message. Use 3-5 words, start with a capital letter, and do not end with a period. 1. Select **Commit changes**. - 1. On the left sidebar, select **Merge requests**. + 1. On the left sidebar, select **Code > Merge requests**. 1. Select **New merge request**. 1. For the source branch, select your fork and branch. If you did not create a branch, select `master`. For the target branch, select the [GitLab repository](https://gitlab.com/gitlab-org/gitlab) `master` branch. diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md index 5cee300481b..a08052bf0e4 100644 --- a/doc/development/documentation/feature_flags.md +++ b/doc/development/documentation/feature_flags.md @@ -72,7 +72,7 @@ FLAG: A `FLAG` note renders on the GitLab documentation site as: FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `example_flag`. +On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](../../administration/feature_flags.md) named `example_flag`. On GitLab.com, this feature is not available. This feature is not ready for production use. @@ -80,15 +80,15 @@ This feature is not ready for production use. | If the feature is... | Use this text | |--------------------------|---------------| -| Available | ``On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](<path to>/administration/feature_flags.md) named `flag_name`.`` | -| Unavailable | ``On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](<path to>/administration/feature_flags.md) named `flag_name`.`` | -| Available to some users | ``On self-managed GitLab, by default this feature is available to a subset of users. To show or hide the feature for all, ask an administrator to [change the status of the feature flag](<path to>/administration/feature_flags.md) named `flag_name`.`` | -| Available, per-group | ``On self-managed GitLab, by default this feature is available. To hide the feature per group, ask an administrator to [disable the feature flag](<path to>/administration/feature_flags.md) named `flag_name`.`` | -| Unavailable, per-group | ``On self-managed GitLab, by default this feature is not available. To make it available per group, ask an administrator to [enable the feature flag](<path to>/administration/feature_flags.md) named `flag_name`.`` | -| Available, per-project | ``On self-managed GitLab, by default this feature is available. To hide the feature per project or for your entire instance, ask an administrator to [disable the feature flag](<path to>/administration/feature_flags.md) named `flag_name`.`` | -| Unavailable, per-project | ``On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](<path to>/administration/feature_flags.md) named `flag_name`.`` | -| Available, per-user | ``On self-managed GitLab, by default this feature is available. To hide the feature per user, ask an administrator to [disable the feature flag](<path to>/administration/feature_flags.md) named `flag_name`.`` | -| Unavailable, per-user | ``On self-managed GitLab, by default this feature is not available. To make it available per user, ask an administrator to [enable the feature flag](<path to>/administration/feature_flags.md) named `flag_name`.`` | +| Available | ``On self-managed GitLab, by default this feature is available. To hide the feature, an administrator can [disable the feature flag](<path to>/administration/feature_flags.md) named `flag_name`.`` | +| Unavailable | ``On self-managed GitLab, by default this feature is not available. To make it available, an administrator can [enable the feature flag](<path to>/administration/feature_flags.md) named `flag_name`.`` | +| Available to some users | ``On self-managed GitLab, by default this feature is available to a subset of users. To show or hide the feature for all, an administrator can [change the status of the feature flag](<path to>/administration/feature_flags.md) named `flag_name`.`` | +| Available, per-group | ``On self-managed GitLab, by default this feature is available. To hide the feature per group, an administrator can [disable the feature flag](<path to>/administration/feature_flags.md) named `flag_name`.`` | +| Unavailable, per-group | ``On self-managed GitLab, by default this feature is not available. To make it available per group, an administrator can [enable the feature flag](<path to>/administration/feature_flags.md) named `flag_name`.`` | +| Available, per-project | ``On self-managed GitLab, by default this feature is available. To hide the feature per project or for your entire instance, an administrator can [disable the feature flag](<path to>/administration/feature_flags.md) named `flag_name`.`` | +| Unavailable, per-project | ``On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, an administrator can [enable the feature flag](<path to>/administration/feature_flags.md) named `flag_name`.`` | +| Available, per-user | ``On self-managed GitLab, by default this feature is available. To hide the feature per user, an administrator can [disable the feature flag](<path to>/administration/feature_flags.md) named `flag_name`.`` | +| Unavailable, per-user | ``On self-managed GitLab, by default this feature is not available. To make it available per user, an administrator can [enable the feature flag](<path to>/administration/feature_flags.md) named `flag_name`.`` | ### GitLab.com availability information @@ -113,7 +113,7 @@ The following examples show the progression of a feature flag. FLAG: On self-managed GitLab, by default this feature is not available. To make it available, -ask an administrator to [enable the feature flag](../administration/feature_flags.md) named `forti_token_cloud`. +an administrator can [enable the feature flag](../administration/feature_flags.md) named `forti_token_cloud`. The feature is not ready for production use. ``` @@ -125,7 +125,7 @@ When the feature is enabled in production, you can update the version history: FLAG: On self-managed GitLab, by default this feature is available. To hide the feature per user, -ask an administrator to [disable the feature flag](../administration/feature_flags.md) named `forti_token_cloud`. +an administrator can [disable the feature flag](../administration/feature_flags.md) named `forti_token_cloud`. ``` And, when the feature is done and fully available to all users: diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 761dde839c1..3f26a5a7f4e 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -223,7 +223,7 @@ merge it as early as possible. ### Linking to `/help` When you're building a new feature, you may need to link to the documentation -from the GitLab application. This is normally done in files inside the +from the GitLab application. This is usually done in files inside the `app/views/` directory, with the help of the `help_page_path` helper method. The `help_page_path` contains the path to the document you want to link to, diff --git a/doc/development/documentation/restful_api_styleguide.md b/doc/development/documentation/restful_api_styleguide.md index c39c7c02108..a5d565ffa79 100644 --- a/doc/development/documentation/restful_api_styleguide.md +++ b/doc/development/documentation/restful_api_styleguide.md @@ -63,7 +63,7 @@ METHOD /endpoint Supported attributes: | Attribute | Type | Required | Description | -|:-------------------------|:---------|:---------|:----------------------| +|--------------------------|----------|----------|-----------------------| | `attribute` | datatype | Yes | Detailed description. | | `attribute` **(<tier>)** | datatype | No | Detailed description. | | `attribute` | datatype | No | Detailed description. | @@ -73,7 +73,7 @@ If successful, returns [`<status_code>`](rest/index.md#status-codes) and the fol response attributes: | Attribute | Type | Description | -|:-------------------------|:---------|:----------------------| +|--------------------------|----------|-----------------------| | `attribute` | datatype | Detailed description. | | `attribute` **(<tier>)** | datatype | Detailed description. | @@ -127,8 +127,8 @@ To deprecate an attribute: 1. Add inline deprecation text to the description. ```markdown - | Attribute | Type | Required | Description | - |:--------------|:-------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------------------| + | Attribute | Type | Required | Description | + |---------------|--------|----------|-------------| | `widget_name` | string | No | [Deprecated](<link-to-issue>) in GitLab 14.7 and is planned for removal in 15.4. Use `widget_id` instead. The name of the widget. | ``` @@ -144,7 +144,7 @@ Sort the table by required attributes first, then alphabetically. ```markdown | Attribute | Type | Required | Description | -|:-----------------------------|:--------------|:---------|:----------------------------------------------------| +|------------------------------|---------------|----------|-----------------------------------------------------| | `title` | string | Yes | Title of the issue. | | `assignee_ids` **(PREMIUM)** | integer array | No | IDs of the users to assign the issue to. | | `confidential` | boolean | No | Sets the issue to confidential. Default is `false`. | @@ -153,7 +153,7 @@ Sort the table by required attributes first, then alphabetically. Rendered example: | Attribute | Type | Required | Description | -|:-----------------------------|:--------------|:---------|:----------------------------------------------------| +|------------------------------|---------------|----------|-----------------------------------------------------| | `title` | string | Yes | Title of the issue. | | `assignee_ids` **(PREMIUM)** | integer array | No | IDs of the users to assign the issue to. | | `confidential` | boolean | No | Sets the issue to confidential. Default is `false`. | @@ -180,7 +180,7 @@ Sort the table alphabetically. ```markdown | Attribute | Type | Description | -|:-----------------------------|:--------------|:------------------------------------------| +|------------------------------|---------------|-------------------------------------------| | `assignee_ids` **(PREMIUM)** | integer array | IDs of the users to assign the issue to. | | `confidential` | boolean | Whether the issue is confidential or not. | | `title` | string | Title of the issue. | @@ -189,7 +189,7 @@ Sort the table alphabetically. Rendered example: | Attribute | Type | Description | -|:-----------------------------|:--------------|:------------------------------------------| +|------------------------------|---------------|-------------------------------------------| | `assignee_ids` **(PREMIUM)** | integer array | IDs of the users to assign the issue to. | | `confidential` | boolean | Whether the issue is confidential or not. | | `title` | string | Title of the issue. | @@ -211,7 +211,7 @@ For information about writing attribute descriptions, see the [GraphQL API descr commands apart into multiple lines. | Methods | Description | -|:------------------------------------------------|:-------------------------------------------------------| +|-------------------------------------------------|--------------------------------------------------------| | `--header "PRIVATE-TOKEN: <your_access_token>"` | Use this method as is, whenever authentication needed. | | `--request POST` | Use this method when creating new objects. | | `--request PUT` | Use this method when updating existing objects. | diff --git a/doc/development/documentation/site_architecture/folder_structure.md b/doc/development/documentation/site_architecture/folder_structure.md index 8a1d9b9fee3..1c9fc1441c4 100644 --- a/doc/development/documentation/site_architecture/folder_structure.md +++ b/doc/development/documentation/site_architecture/folder_structure.md @@ -17,7 +17,7 @@ API. Our goal is to have a clear hierarchical structure with meaningful URLs like `docs.gitlab.com/user/project/merge_requests/`. With this pattern, you can immediately tell that you are navigating to user-related documentation about -Project features; specifically about Merge Requests. Our site's paths match +project features; specifically about merge requests. Our site's paths match those of our repository, so the clear structure also makes documentation easier to update. @@ -26,13 +26,20 @@ Put files for a specific product area into the related folder: | Directory | Contents | |:----------------------|:------------------| | `doc/user/` | Documentation for users. Anything that can be done in the GitLab user interface goes here, including usage of the `/admin` interface. | -| `doc/administration/` | Documentation that requires the user to have access to the server where GitLab is installed. Administrator settings in the GitLab user interface are under `doc/user/admin_area/`. | +| `doc/administration/` | Documentation that requires the user to have access to the server where GitLab is installed. Administrator settings in the GitLab user interface are under `doc/administration/`. | | `doc/api/` | Documentation for the API. | | `doc/development/` | Documentation related to the development of GitLab, whether contributing code or documentation. Related process and style guides should go here. | | `doc/legal/` | Legal documents about contributing to GitLab. | | `doc/install/` | Instructions for installing GitLab. | | `doc/update/` | Instructions for updating GitLab. | -| `doc/topics/` | Indexes per topic (`doc/topics/topic_name/index.md`): all resources for that topic. | +| `doc/tutorials/` | Tutorials for how to use GitLab. | + +The following are legacy or deprecated folders. +Do not add new content to these folders: + +- `/gitlab-basics/` +- `/topics/` +- `/university/` ## Work with directories and files @@ -45,33 +52,18 @@ When working with directories and files: 1. When creating or renaming a file or directory and it has more than one word in its name, use underscores (`_`) instead of spaces or dashes. For example, proper naming would be `import_project/import_from_github.md`. This applies - to both image files and Markdown files. -1. For image files, do not exceed 100KB. + to both [image files](../styleguide/index.md#images) and Markdown files. 1. Do not upload video files to the product repositories. [Link or embed videos](../styleguide/index.md#videos) instead. -1. There are four main directories: `user`, `administration`, `api`, and - `development`. -1. The `doc/user/` directory has five main subdirectories: `project/`, `group/`, - `profile/`, `dashboard/` and `admin_area/`. +1. In the `doc/user/` directory: - `doc/user/project/` should contain all project related documentation. - `doc/user/group/` should contain all group related documentation. - `doc/user/profile/` should contain all profile related documentation. Every page you would navigate under `/profile` should have its own document, for example, `account.md`, `applications.md`, or `emails.md`. - - `doc/user/dashboard/` should contain all dashboard related documentation. - - `doc/user/admin_area/` should contain all administrator-related - documentation describing what can be achieved by accessing the GitLab - administrator interface (not to be confused with `doc/administration` where - server access is required). - - Every category under `/admin/application_settings/` should have its - own document located at `doc/user/admin_area/settings/`. For example, - the **Visibility and Access Controls** category should have a document - located at `doc/user/admin_area/settings/visibility_and_access_controls.md`. -1. The `doc/topics/` directory holds topic-related technical content. Create - `doc/topics/topic_name/subtopic_name/index.md` when subtopics become necessary. - General user and administrator documentation should be placed accordingly. -1. The `/university/` directory is *deprecated* and the majority of its documentation - has been moved. +1. In the `doc/administration/` directory: all administrator-related + documentation for administrators, including admin tasks done in both + the UI and on the backend servers. If you're unsure where to place a document or a content addition, this shouldn't stop you from authoring and contributing. Use your best judgment, and then ask diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index 6a56d824e35..bd4ded8ca11 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -133,7 +133,7 @@ the team is happy to review and improve upon your content. Review the [Documentation guidelines](index.md) before you begin your first documentation MR. Maintaining a knowledge base separate from the documentation would -be against the documentation-first methodology, because the content would overlap with +be against the documentation-first methodology because the content would overlap with the documentation. ## Writing for localization @@ -190,6 +190,8 @@ Use backticks for: - [Code blocks](#code-blocks). - Error messages. +- Commands, parameters, and filenames. +- Values. For example: "In the **Name** text box, type `test`." ### Markdown Rules @@ -379,7 +381,7 @@ If you use an acronym, spell it out on first use on a page. You do not need to s ### Numbers -When using numbers in text, spell out zero through nine, and use numbers for 10 and greater. For details, see the [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/numbers). +For numbers in text, spell out zero through nine and use numbers for 10 and greater. For more information, see the [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/numbers). ## Text @@ -698,6 +700,9 @@ page), use these phrases: | No | `**{dotted-circle}** No` | **{dotted-circle}** No | | Yes | `**{check-circle}** Yes` | **{check-circle}** Yes | +Don't use `**{dotted-circle}**` and `**{check-circle}**` in API documentation. +Instead, follow the [API topic template](../restful_api_styleguide.md#api-topic-template). + ### Footnotes To indicate a footnote, use the HTML tag `<sup>` with a number. @@ -821,7 +826,7 @@ For example: You can expand on this text by using phrases like `For more information about this feature, see...` -Do not to use the following constructions: +Do not use the following constructions: - `Learn more about...` - `To read more...`. @@ -878,7 +883,7 @@ If you must use one of these links: - If the link is to a confidential issue, mention that the issue is visible only to GitLab team members, as in the first example. - If the link requires a specific role or permissions, mention that information, as in the second example. -- Put the link in backticks, so that it does not cause link checkers to fail. +- Put the link in backticks so that it does not cause link checkers to fail. Examples: @@ -909,7 +914,7 @@ document to ensure it links to the most recent version of the file. ## Navigation -When documenting how to navigate through the GitLab UI: +When documenting how to navigate the GitLab UI: - Always use location, then action. - From the **Visibility** dropdown list (location), select **Public** (action). @@ -968,13 +973,13 @@ To open either project or group settings: To create a project: ```markdown -1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New project/repository**. +1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**. ``` To create a group: ```markdown -1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New group**. +1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New group**. ``` To open the Admin Area: @@ -1196,7 +1201,7 @@ include a visual representation to help readers understand it, you can: an area of the screen. - Create a short video of the interaction and link to it. -## Emojis +## Emoji Don't use the Markdown emoji format, for example `:smile:`, for any purpose. Use [GitLab SVG icons](#gitlab-svg-icons) instead. @@ -1546,11 +1551,20 @@ When names change, it is more complicated to search or grep text that has line b Tier badges are displayed as orange text next to a topic title. These badges link to the GitLab pricing page. -You must assign a tier badge: +You should assign a tier badge: - To all H1 topic titles, except the pages under `doc/development/*`. - To topic titles that don't apply to the same tier as the H1. +The H1 tier badge should be the badge that applies to the lowest tier for the features on the page. + +Some pages won't have a tier badge, because no obvious tier badge applies. For example: + +- Tutorials. +- Pages that compare features from different tiers. + +#### Add a tier badge + To add a tier badge to a topic title, add the relevant tier badge after the title text. For example: diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md index 0bbd679abe5..84ab2ecc4e9 100644 --- a/doc/development/documentation/styleguide/word_list.md +++ b/doc/development/documentation/styleguide/word_list.md @@ -152,7 +152,7 @@ Instead of: - This feature enables users to add files to their repository. This phrasing is more active and is from the user perspective, rather than the person who implemented the feature. -[View details in the Microsoft style guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/allow-allows). +For more information, see the [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/allow-allows). ## analytics @@ -169,8 +169,8 @@ Instead of **and/or**, use **or** or rewrite the sentence to spell out both opti ## and so on -Do not use **and so on**. Instead, be more specific. For details, see -[the Microsoft style guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/and-so-on). +Do not use **and so on**. Instead, be more specific. For more information, see the +[Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/and-so-on). ## area @@ -284,7 +284,7 @@ CI/CD is always uppercase. No need to spell it out on first use. ## CI/CD minutes -Do not use **CI/CD minutes**. This term was renamed to [**units of compute**](#units-of-compute). +Do not use **CI/CD minutes**. This term was renamed to [**compute minutes**](#compute-minutes). ## click @@ -318,16 +318,30 @@ Use **compute** for the resources used by runners to run CI/CD jobs. Related terms: -- [**units of compute**](#units-of-compute): How compute usage is calculated. For example, `400 units of compute`. -- [**compute quota**](../../../ci/pipelines/cicd_minutes.md): The limit of units of compute that a namespace can use each month. -- **compute usage**: The number of units of compute that the namespace has used from the monthly quota. +- [**compute minutes**](#compute-minutes): How compute usage is calculated. For example, `400 compute minutes`. +- [**compute quota**](../../../ci/pipelines/cicd_minutes.md): The limit of compute minutes that a namespace can use each month. +- **compute usage**: The number of compute minutes that the namespace has used from the monthly quota. + +## compute minutes + +Use **compute minutes** instead of these (or similar) terms: + +- **CI/CD minutes** +- **CI minutes** +- **pipeline minutes** +- **CI pipeline minutes** +- **pipeline minutes** + +For more information, see [epic 2150](https://gitlab.com/groups/gitlab-com/-/epics/2150). ## confirmation dialog -Use **confirmation dialog** to describe the dialog box that asks you to confirm your action. For example: +Use **confirmation dialog** to describe the dialog that asks you to confirm an action. For example: - On the confirmation dialog, select **OK**. +Do not use **confirmation box** or **confirmation dialog box**. See also [**dialog**](#dialog). + ## Container Registry Use title case for the GitLab Container Registry. @@ -387,9 +401,29 @@ When writing about the Developer role: Do not use **Developer permissions**. A user who is assigned the Developer role has a set of associated permissions. +## dialog + +Use **dialog** rather than any of these alternatives: + +- **dialog box** +- **modal** +- **modal dialog** +- **modal window** +- **pop-up** +- **pop-up window** +- **window** + +See also [**confirmation dialog**](#confirmation-dialog). For more information, see the [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/d/dialog-box-dialog-dialogue). + +When the dialog is the location of an action, use **on** as a preposition. For example: + +- On the **Grant permission** dialog, select **Group**. + +See also [**on**](#on). + ## disable -See [the Microsoft style guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/d/disable-disabled) for guidance on **disable**. +See the [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/d/disable-disabled) for guidance on **disable**. 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)) ## disallow @@ -439,17 +473,30 @@ Do not use **easily**. If the user doesn't find the process to be easy, we lose 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)) +## ellipsis + +When documenting UI text, if the UI includes an ellipsis, do not include the ellipsis in the documentation. +For more information, see the [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/punctuation/ellipses). + +Use: + +- **Create new** + +Instead of: + +- **Create new...** + ## email Do not use **e-mail** with a hyphen. When plural, use **emails** or **email messages**. ([Vale](../testing.md#vale) rule: [`SubstitutionSuggestions.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/SubstitutionSuggestions.yml)) -## emojis +## emoji -Use **emojis** to refer to the plural form of **emoji**. +Use **emoji** to refer to the plural form of **emoji**. ## enable -See [the Microsoft style guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/e/enable-enables) for guidance on **enable**. +See the [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/e/enable-enables) for guidance on **enable**. Use **active** or **on** instead. ([Vale](../testing.md#vale) rule: [`InclusionAbleism.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/InclusionAbleism.yml)) ## enter @@ -680,7 +727,7 @@ Instead of: ## I -Do not use first-person singular. Use **you**, **we**, or **us** instead. ([Vale](../testing.md#vale) rule: [`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml)) +Do not use first-person singular. Use **you** or rewrite the phrase instead. ## i.e. @@ -862,15 +909,27 @@ Do not use `master`. Use `main` when you need a sample [default branch name](#de ## may, might -**Might** means something has the probability of occurring. **May** gives permission to do something. Consider **can** instead of **may**. +**Might** means something has the probability of occurring. Might is often used in troubleshooting documentation. -## MB, megabytes +**May** gives permission to do something. Consider **can** instead of **may**. -For **MB** and **GB**, follow the [Microsoft guidance](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/bits-bytes-terms). +Consider rewording phrases that use these terms. These terms often indicate possibility and doubt, and technical writing strives to be precise. -## me, myself, mine +See also [you can](#you-can). + +Use: + +- The `committed_date` and `authored_date` fields are generated from different sources, and might not be identical. +- A typical pipeline consists of four stages, executed in the following order: + +Instead of: -Do not use first-person singular. Use **you**, **we**, or **us** instead. ([Vale](../testing.md#vale) rule: [`FirstPerson.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/FirstPerson.yml)) +- The `committed_date` and `authored_date` fields are generated from different sources, and may not be identical. +- A typical pipeline might consist of four stages, executed in the following order: + +## MB, megabytes + +For **MB** and **GB**, follow the [Microsoft guidance](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/bits-bytes-terms). ## member @@ -1009,15 +1068,12 @@ For more information, see the ## on -When documenting how to select high-level UI elements, use the word **on**. +When documenting high-level UI elements, use **on** as a preposition. For example: -Use: +- On the left sidebar, select **Settings > CI/CD**. +- On the **Grant permission** dialog, select **Group**. -- `On the left sidebar...` - -Instead of: - -- Do not: `From the left sidebar...` or `In the left sidebar...` +Do not use **from** or **in**. For more information, see the [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/f/from-vs-on). ## once @@ -1098,7 +1154,7 @@ Use lowercase for **personal access token**. ## please -Do not use **please**. For details, see the [Microsoft style guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please). +Do not use **please**. For more information, see the [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/p/please). ## Premium @@ -1453,9 +1509,9 @@ Use [**2FA** and **two-factor authentication**](#2fa-two-factor-authentication) ## type -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. +Use **type** when the cursor remains where you're typing. For example, +in a search box, you begin typing and search results appear. You do not +click out of the search box. For example: @@ -1470,25 +1526,13 @@ See also [**enter**](#enter). Use **Ultimate**, in uppercase, for the subscription tier. When you refer to **Ultimate** in the context of other subscription tiers, follow [the subscription tier](#subscription-tier) guidance. -## units of compute - -Use **units of compute** instead of these (or similar) terms: - -- **CI/CD minutes** -- **CI minutes** -- **pipeline minutes** -- **CI pipeline minutes** -- **pipeline minutes** - -For more information, see [issue 5218](https://gitlab.com/gitlab-com/Product/-/issues/5218). - ## units of measurement Use a space between the number and the unit of measurement. For example, **128 GB**. ([Vale](../testing.md#vale) rule: [`Units.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Units.yml)) -For other guidance, follow -[the Microsoft style guidelines](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/bits-bytes-terms). +For more information, see the +[Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/bits-bytes-terms). ## update @@ -1524,7 +1568,7 @@ If the UI element is not in a corner, use **upper left** and **upper right**. Do not use **top left** and **top right**. -For details, see the [Microsoft style guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/u/upper-left-upper-right). +For more information, see the [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/u/upper-left-upper-right). ## useful @@ -1571,7 +1615,7 @@ Instead of: - While job 1 can run quickly, job 2 is more precise. -For details, see the [Microsoft style guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/w/while). +For more information, see the [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/w/while). ## whilst @@ -1616,6 +1660,7 @@ For example: - Use code review analytics to view merge request data. - Create a board to organize your team tasks. - Configure variables to restrict pushes to a repository. +- Add links to external accounts you have, like Skype and Twitter. Use **you can** for optional actions. For example: diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md index 1a4194aebd9..eb1ea28d3b8 100644 --- a/doc/development/documentation/workflow.md +++ b/doc/development/documentation/workflow.md @@ -69,7 +69,7 @@ Remember: GitLab documentation is distributed under the [CC BY-SA 4.0 license](https://creativecommons.org/licenses/by-sa/4.0/), which presupposes that GitLab owns the documentation. -Under current law in the US and the EU, it’s possible that AI-generated works might either: +Under current law in the US and the EU, it's possible that AI-generated works might either: - not be owned by anyone because they weren't created by a human, or - belong to the AI training data's creator, if the AI verbatim reproduces content that it trained on |