Merge branch '276207-vale-substitutions-warning-part-02' into 'master'

Docs: clean up some Vale substitution warnings

See merge request gitlab-org/gitlab!51048

doc/user/project/web_ide/index.md

@@ -33,8 +33,8 @@ start seeing results.
 ## Command palette
 
 You can see all available commands for manipulating editor content by pressing
-the <kbd>F1</kbd> key when the editor is in focus. After that,
-you'll see a complete list of available commands for
+the <kbd>F1</kbd> key when the editor is in focus. After that, the editor displays
+a complete list of available commands for
 manipulating editor content. The editor supports commands for multi-cursor
 editing, code block folding, commenting, searching and replacing, navigating
 editor warnings and suggestions, and more.
@@ -47,7 +47,7 @@ the command without having to select it in the command palette.
 
 ## Syntax highlighting
 
-As expected from an IDE, syntax highlighting for many languages within
+As expected from an IDE, syntax highlighting for many languages in
 the Web IDE makes your direct editing even easier.
 
 The Web IDE currently provides:
@@ -78,7 +78,7 @@ All the themes GitLab supports for syntax highlighting are added to the Web IDE'
 You can pick a theme from your [profile preferences](../../profile/preferences.md).
 
 The themes are available only in the Web IDE file editor, except for the [dark theme](https://gitlab.com/gitlab-org/gitlab/-/issues/209808) and
-the [solarized dark theme](https://gitlab.com/gitlab-org/gitlab/-/issues/219228),
+the [Solarized dark theme](https://gitlab.com/gitlab-org/gitlab/-/issues/219228),
 which apply to the entire Web IDE screen.
 
 | Solarized Light Theme                                         | Solarized Dark Theme                                        | Dark Theme                              |
@@ -144,12 +144,13 @@ schemas:
 
 Each schema entry supports two properties:
 
-- `uri`: please provide an absolute URL for the schema definition file here. The schema from this URL
-is loaded when a matching file is open.
-- `match`: a list of matching paths or glob expressions. If a schema matches a particular path pattern,
-it will be applied to that file. Please enclose the pattern in quotes if it begins with an asterisk (`*`),
-it's be applied to that file. If a pattern begins with an asterisk (`*`), enclose it in quotation
-marks. Otherwise, the configuration file is not valid YAML.
+- `uri`: please provide an absolute URL for the schema definition file here.
+  The schema from this URL is loaded when a matching file is open.
+- `match`: a list of matching paths or glob expressions. If a schema matches a
+  particular path pattern, it is applied to that file. Please enclose the pattern
+  in quotes if it begins with an asterisk (`*`), it's be applied to that file.
+  If a pattern begins with an asterisk (`*`), enclose it in quotation marks.
+  Otherwise, the configuration file is not valid YAML.
 
 ## Configure the Web IDE
 
@@ -180,7 +181,7 @@ The Web IDE currently supports the following `.editorconfig` settings:
 After making your changes, click the **Commit** button on the bottom-left to
 review the list of changed files.
 
-Once you have finalized your changes, you can add a commit message, commit the
+After you have finalized your changes, you can add a commit message, commit the
 changes and directly create a merge request. In case you don't have write
 access to the selected branch, you see a warning, but can still create
 a new branch and start a merge request.
@@ -268,7 +269,7 @@ GitLab.com
 
 ![Administrator Live Preview setting](img/admin_live_preview_v13_0.png)
 
-Once you have done that, you can preview projects with a `package.json` file and
+After you have done that, you can preview projects with a `package.json` file and
 a `main` entry point inside the Web IDE. An example `package.json` is shown
 below.
 
@@ -325,7 +326,7 @@ In order to enable the Web IDE terminals you need to create the file
 file is fairly similar to the [CI configuration file](../../../ci/yaml/README.md)
 syntax but with some restrictions:
 
-- No global blocks can be defined (i.e., `before_script` or `after_script`)
+- No global blocks (such as `before_script` or `after_script`) can be defined.
 - Only one job named `terminal` can be added to this file.
 - Only the keywords `image`, `services`, `tags`, `before_script`, `script`, and
   `variables` are allowed to be used to configure the job.
@@ -350,7 +351,7 @@ terminal:
     NODE_ENV: "test"
 ```
 
-Once the terminal has started, the console is displayed and we could access
+After the terminal has started, the console is displayed and we could access
 the project repository files.
 
 **Important**. The terminal job is branch dependent. This means that the
@@ -364,7 +365,7 @@ If there is no configuration file in a branch, an error message is shown.
 If Interactive Terminals are available for the current user, the **Terminal** button is visible in the right sidebar of the Web IDE. Click this button to open
 or close the terminal tab.
 
-Once open, the tab shows the **Start Web Terminal** button. This button may
+After opening, the tab shows the **Start Web Terminal** button. This button may
 be disabled if the environment is not configured correctly. If so, a status
 message describes the issue. Here are some reasons why **Start Web Terminal**
 may be disabled:
@@ -378,7 +379,7 @@ can be closed and reopened and the state of the terminal is not affected.
 
 When the terminal is started and is successfully connected to the runner, then the
 runner's shell prompt appears in the terminal. From here, you can enter
-commands executed within the runner's environment. This is similar
+commands executed in the runner's environment. This is similar
 to running commands in a local terminal or through SSH.
 
 While the terminal is running, it can be stopped by clicking **Stop Terminal**.
@@ -426,7 +427,7 @@ terminal:
   [predefined environment variable](../../../ci/variables/predefined_variables.md)
   for GitLab Runners. This is where your project's repository resides.
 
-Once you have configured the web terminal for file syncing, then when the web
+After you have configured the web terminal for file syncing, then when the web
 terminal is started, a **Terminal** status is visible in the status bar.
 
 ![Web IDE Client Side Evaluation](img/terminal_status.png)
@@ -434,7 +435,7 @@ terminal is started, a **Terminal** status is visible in the status bar.
 Changes made to your files via the Web IDE sync to the running terminal
 when:
 
-- <kbd>Ctrl</kbd> + <kbd>S</kbd> (or <kbd>Cmd</kbd> + <kbd>S</kbd> on Mac)
+- <kbd>Control</kbd> + <kbd>S</kbd> (or <kbd>Command</kbd> + <kbd>S</kbd> on Mac)
   is pressed while editing a file.
 - Anything outside the file editor is clicked after editing a file.
 - A file or folder is created, deleted, or renamed.
@@ -446,7 +447,7 @@ The Web IDE has a few limitations:
 - Interactive Terminals is in a beta phase and continues to be improved in upcoming releases. In the meantime, please note that the user is limited to having only one
   active terminal at a time.
 
-- LFS files can be rendered and displayed but they cannot be updated and committed using the Web IDE. If an LFS file is modified and pushed to the repository, the LFS pointer in the repository will be overwritten with the modified LFS file content.
+- LFS files can be rendered and displayed but they cannot be updated and committed using the Web IDE. If an LFS file is modified and pushed to the repository, the LFS pointer in the repository is overwritten with the modified LFS file content.
 
 ### Troubleshooting
 

doc/user/search/index.md

@@ -18,7 +18,7 @@ The number displayed on their right represents the number of issues and merge re
 
 ![issues and MRs dashboard links](img/dashboard_links.png)
 
-When you click **Issues**, you'll see the opened issues assigned to you straight away:
+When you click **Issues**, the opened issues assigned to you are shown straight away:
 
 ![Issues assigned to you](img/issues_assigned_to_you.png)
 
@@ -29,7 +29,7 @@ You can also filter the results using the search and filter field, as described
 
 ### Issues and MRs assigned to you or created by you
 
-You'll also find shortcuts to issues and merge requests created by you or assigned to you
+GitLab shows shortcuts to issues and merge requests created by you or assigned to you
 on the search field on the top-right of your screen:
 
 ![shortcut to your issues and merge requests](img/issues_mrs_shortcut.png)
@@ -40,7 +40,7 @@ on the search field on the top-right of your screen:
 > - Filtering by child Epics was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9029) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0.
 > - Filtering by Iterations was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118742) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.6.
 
-Follow these steps to filter the **Issues** and **Merge Requests** list pages within projects and
+Follow these steps to filter the **Issues** and **Merge Requests** list pages in projects and
 groups:
 
 1. Click in the field **Search or filter results...**.
@@ -74,7 +74,7 @@ Some filter fields like milestone and assignee, allow you to filter by **None**
 
 ![filter by none any](img/issues_filter_none_any.png)
 
-Selecting **None** returns results that have an empty value for that field. E.g.: no milestone, no assignee.
+Selecting **None** returns results that have an empty value for that field. For example: no milestone, no assignee.
 
 Selecting **Any** does the opposite. It returns results that have a non-empty value for that field.
 
@@ -83,11 +83,11 @@ Selecting **Any** does the opposite. It returns results that have a non-empty va
 You can filter issues and merge requests by specific terms included in titles or descriptions.
 
 - Syntax
-  - Searches look for all the words in a query, in any order. E.g.: searching
-    issues for `display bug` will return all issues matching both those words, in any order.
+  - Searches look for all the words in a query, in any order. For example: searching
+    issues for `display bug` returns all issues matching both those words, in any order.
   - To find the exact term, use double quotes: `"display bug"`
 - Limitation
-  - For performance reasons, terms shorter than 3 chars are ignored. E.g.: searching
+  - For performance reasons, terms shorter than 3 chars are ignored. For example: searching
     issues for `included in titles` is same as `included titles`
   - Search is limited to 4096 characters and 64 terms per query.
 
@@ -157,7 +157,7 @@ relevant users or other attributes.
 
 For performance optimization, there is a requirement of a minimum of three
 characters to begin your search. For example, if you want to search for
-issues that have the assignee "Simone Presley", you'll need to type at
+issues that have the assignee "Simone Presley", you must type at
 least "Sim" before autocomplete gives any relevant results.
 
 ## Search history
@@ -170,11 +170,11 @@ You can view recent searches by clicking on the little arrow-clock icon, which i
 
 Individual filters can be removed by clicking on the filter's (x) button or backspacing. The entire search filter can be cleared by clicking on the search box's (x) button or via <kbd>⌘</kbd> (Mac) + <kbd>⌫</kbd>.
 
-To delete filter tokens one at a time, the <kbd>⌥</kbd> (Mac) / <kbd>Ctrl</kbd> + <kbd>⌫</kbd> keyboard combination can be used.
+To delete filter tokens one at a time, the <kbd>⌥</kbd> (Mac) / <kbd>Control</kbd> + <kbd>⌫</kbd> keyboard combination can be used.
 
 ## Filtering with multiple filters of the same type
 
-Some filters can be added multiple times. These include but are not limited to assignees and labels. When you filter with these multiple filters of the same type, the AND logic is applied. For example, if you were filtering `assignee:@sam assignee:@sarah`, your results will only include entries whereby the assignees are assigned to both Sam and Sarah are returned.
+Some filters can be added multiple times. These include but are not limited to assignees and labels. When you filter with these multiple filters of the same type, the AND logic is applied. For example, if you were filtering `assignee:@sam assignee:@sarah`, your results include only entries whereby the assignees are assigned to both Sam and Sarah are returned.
 
 ![multiple assignees filtering](img/multiple_assignees.png)
 
@@ -190,7 +190,7 @@ author, type, and action. Also, you can sort them by
 
 You can search through your projects from the left menu, by clicking the menu bar, then **Projects**.
 On the field **Filter by name**, type the project or group name you want to find, and GitLab
-will filter them for you as you type.
+filters them for you as you type.
 
 You can also look for the projects you [starred](../project/index.md#star-a-project) (**Starred projects**), and **Explore** all
 public and internal projects available in GitLab.com, from which you can filter by visibility,
@@ -207,7 +207,7 @@ Similarly to [projects search](#projects), you can search through your groups fr
 the left menu, by clicking the menu bar, then **Groups**.
 
 On the field **Filter by name**, type the group name you want to find, and GitLab
-will filter them for you as you type.
+filters them for you as you type.
 
 You can also **Explore** all public and internal groups available in GitLab.com,
 and sort them by **Last created**, **Oldest created**, **Last updated**, or **Oldest updated**.
@@ -219,15 +219,15 @@ You can also filter them by name (issue title), from the field **Filter by name*
 
 When you want to search for issues to add to lists present in your Issue Board, click
 the button **Add issues** on the top-right of your screen, opening a modal window from which
-you'll be able to, besides filtering them by **Name**, **Author**, **Assignee**, **Milestone**,
+you can, besides filtering them by **Name**, **Author**, **Assignee**, **Milestone**,
 and **Labels**, select multiple issues to add to a list of your choice:
 
 ![search and select issues to add to board](img/search_issues_board.png)
 
 ## Shortcut
 
-You'll find a shortcut on the search field on the top-right of the project's dashboard to
-quickly access issues and merge requests created or assigned to you within that project:
+GitLab shows a shortcut on the search field on the top-right of the project's dashboard to
+quickly access issues and merge requests created or assigned to you in that project:
 
 ![search per project - shortcut](img/project_search.png)
 
@@ -242,12 +242,12 @@ You can also type in this search bar to see autocomplete suggestions for:
 - Recently viewed issues (try and type some word from the title of a recently viewed issue)
 - Recently viewed merge requests (try and type some word from the title of a recently viewed merge request)
 - Recently viewed epics (try and type some word from the title of a recently viewed epic)
-- [GitLab Flavored Markdown](../markdown.md#special-gitlab-references) (GFM) for issues within a project (try and type a GFM reference for an issue)
+- [GitLab Flavored Markdown](../markdown.md#special-gitlab-references) (GFM) for issues in a project (try and type a GFM reference for an issue)
 
 ## Basic search
 
 The Basic search in GitLab is a global search service that allows you to search
-across the entire GitLab instance, within a group, or a single project. Basic search is
+across the entire GitLab instance, in a group, or in a single project. Basic search is
 backed by the database and allows searching in:
 
 - Projects
@@ -262,12 +262,12 @@ backed by the database and allows searching in:
 - Wiki (Project only)
 
 To start a search, type into the search bar on the top-right of the screen. You can always search
-in all GitLab and may also see the options to search within a group or project if you are in the
+in all GitLab and may also see the options to search in a group or project if you are in the
 group or project dashboard.
 
 ![basic search](img/basic_search.png)
 
-Once the results are returned, you can modify the search, select a different type of data to
+After the results are returned, you can modify the search, select a different type of data to
 search, or choose a specific group or project.
 
 ![basic_search_results](img/basic_search_results.png)
@@ -282,11 +282,11 @@ the search field on the top-right of your screen while the project page is open.
 
 ### SHA search
 
-You can quickly access a commit from within the project dashboard by entering the SHA
-into the search field on the top right of the screen. If a single result is found, you will be
+You can quickly access a commit from the project dashboard by entering the SHA
+into the search field on the top right of the screen. If a single result is found, you are
 redirected to the commit result and given the option to return to the search results page.
 
-![project sha search redirect](img/project_search_sha_redirect.png)
+![project SHA search redirect](img/project_search_sha_redirect.png)
 
 ## Advanced Search **(STARTER)**
 
@@ -314,7 +314,7 @@ This feature might not be available to you. Check the **version history** note a
 
 You can search inside the project’s settings sections by entering a search
 term in the search box located at the top of the page. The search results
-will appear highlighted in the sections that match the search term.
+appear highlighted in the sections that match the search term.
 
 ![Search project settings](img/project_search_general_settings_v13_8.png)
 

doc/user/snippets.md

@@ -69,8 +69,8 @@ new commit to the master branch is recorded. Commit messages are automatically
 generated. The snippet's repository has only one branch (master) by default, deleting
 it or creating other branches is not supported.
 
-Existing snippets will be automatically migrated in 13.0. Their current
-content will be saved as the initial commit to the snippets' repository.
+Existing snippets are automatically migrated in 13.0. Their current
+content is saved as the initial commit to the snippets' repository.
 
 ### Filenames
 
@@ -86,10 +86,10 @@ number increases incrementally when more snippets without an attributed
 filename are added.
 
 When upgrading from an earlier version of GitLab to 13.0, existing snippets
-without a supported filename will be renamed to a compatible format. For
-example, if the snippet's filename is `http://a-weird-filename.me` it will
-be changed to `http-a-weird-filename-me` to be included in the snippet's
-repository. As snippets are stored by ID, changing their filenames will not break
+without a supported filename are renamed to a compatible format. For
+example, if the snippet's filename is `http://a-weird-filename.me` it is
+changed to `http-a-weird-filename-me` to be included in the snippet's
+repository. As snippets are stored by ID, changing their filenames breaks
 direct or embedded links to the snippet.
 
 ### Multiple files by Snippet
@@ -105,8 +105,8 @@ to a certain context. For example:
 - A snippet with a `docker-compose.yml` file and its associated `.env` file.
 - A `gulpfile.js` file coupled with a `package.json` file, which together can be used to bootstrap a project and manage its dependencies.
 
-Snippets support between 1 and 10 files. They can be managed via Git (since they're [versioned](#versioned-snippets)
-by a Git repository), through the [Snippets API](../api/snippets.md), or within the GitLab UI.
+Snippets support between 1 and 10 files. They can be managed via Git (because they're [versioned](#versioned-snippets)
+by a Git repository), through the [Snippets API](../api/snippets.md), or in the GitLab UI.
 
 ![Multi-file Snippet](img/gitlab_snippet_v13_5.png)
 
@@ -139,7 +139,7 @@ master branch.
 
 ### Reduce snippets repository size
 
-Since versioned Snippets are considered as part of the [namespace storage size](../user/admin_area/settings/account_and_limit_settings.md),
+Because versioned Snippets are considered as part of the [namespace storage size](../user/admin_area/settings/account_and_limit_settings.md),
 it's recommended to keep snippets' repositories as compact as possible.
 
 For more information about tools to compact repositories,
@@ -151,7 +151,7 @@ see the documentation on [reducing repository size](../user/project/repository/r
 - Creating or deleting branches is not supported. Only a default *master* branch is used.
 - Git tags are not supported in snippet repositories.
 - Snippets' repositories are limited to 10 files. Attempting to push more
-than 10 files will result in an error.
+than 10 files results in an error.
 - Revisions are not *yet* visible to the user on the GitLab UI, but
 it's planned to be added in future iterations. See the [revisions tab issue](https://gitlab.com/gitlab-org/gitlab/-/issues/39271)
 for updates.
@@ -187,9 +187,9 @@ facilitating the collaboration among users.
 
 You can download the raw content of a snippet.
 
-By default snippets will be downloaded with Linux-style line endings (`LF`). If
+By default snippets are downloaded with Linux-style line endings (`LF`). If
 you want to preserve the original line endings you need to add a parameter `line_ending=raw`
-(e.g., `https://gitlab.com/snippets/SNIPPET_ID/raw?line_ending=raw`). In case a
+(For example: `https://gitlab.com/snippets/SNIPPET_ID/raw?line_ending=raw`). In case a
 snippet was created using the GitLab web interface the original line ending is Windows-like (`CRLF`).
 
 ## Embedded snippets
@@ -207,7 +207,7 @@ To embed a snippet, first make sure that:
 - In **Project > Settings > Permissions**, the snippets permissions are
   set to **Everyone with access**
 
-Once the above conditions are met, the "Embed" section will appear in your
+After the above conditions are met, the "Embed" section appears in your
 snippet where you can simply click on the "Copy" button. This copies a one-line
 script that you can add to any website or blog post.