Merge branch 'docs-aqualls-create-future-tense' into 'master'

Fixing warnings in the Create docset

See merge request gitlab-org/gitlab!52642

doc/development/approval_rules.md

@@ -44,8 +44,8 @@ erDiagram
 ### `Project` and `MergeRequest`
 
 `Project` and `MergeRequest` models are defined in `ee/app/models/ee/project.rb`
-and `ee/app/models/ee/merge_request.rb`. They extend the non-EE versions since
-approval rules is an EE only feature. Associations and other related stuff to
+and `ee/app/models/ee/merge_request.rb`. They extend the non-EE versions, because
+approval rules are an EE-only feature. Associations and other related stuff to
 merge request approvals are defined here.
 
 ### `ApprovalState`
@@ -265,8 +265,8 @@ graph LR
   ApprovalWrappedRule --> Approval
 ```
 
-This flow gets initiated by the frontend component. The data returned will
-then be used to display information on the MR widget.
+This flow gets initiated by the frontend component. The data returned is
+used to display information on the MR widget.
 
 ### Approving a merge request
 
@@ -282,5 +282,5 @@ is executed instead.
 
 ## TODO
 
-1. Add information related to other rule types (e.g. `code_owner` and `report_approver`).
+1. Add information related to other rule types, such as `code_owner` and `report_approver`.
 1. Add information about side effects of approving/unapproving merge request.

doc/development/fe_guide/editor_lite.md

@@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 ## Background
 
-**Editor Lite** is a technological product driving [Web Editor](../../user/project/repository/web_editor.md), [Snippets](../../user/snippets.md), [CI Linter](../../ci/lint.md), etc. Editor Lite is the driving technology for any single-file editing experience across the product.
+**Editor Lite** is a technological product driving features like [Web Editor](../../user/project/repository/web_editor.md), [Snippets](../../user/snippets.md), and [CI Linter](../../ci/lint.md). Editor Lite is the driving technology for any single-file editing experience across the product.
 
 Editor Lite is a thin wrapper around [the Monaco editor](https://microsoft.github.io/monaco-editor/index.html) that provides the necessary helpers and abstractions and extends Monaco using extensions.
 

doc/development/gitaly.md

@@ -12,9 +12,10 @@ Workhorse and GitLab Shell.
 
 ## Deep Dive
 
-In May 2019, Bob Van Landuyt hosted a Deep Dive (GitLab team members only: `https://gitlab.com/gitlab-org/create-stage/issues/1`)
-on the [Gitaly project](https://gitlab.com/gitlab-org/gitaly) and how to contribute to it as a
-Ruby developer, to share his domain specific knowledge with anyone who may work in this part of the
+In May 2019, <!-- vale gitlab.Spelling = NO --> Bob Van Landuyt <!-- vale gitlab.Spelling = YES -->
+hosted a Deep Dive (GitLab team members only: `https://gitlab.com/gitlab-org/create-stage/issues/1`)
+on the [Gitaly project](https://gitlab.com/gitlab-org/gitaly). It included how to contribute to it as a
+Ruby developer, and shared domain-specific knowledge with anyone who may work in this part of the
 codebase in the future.
 
 You can find the <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [recording on YouTube](https://www.youtube.com/watch?v=BmlEWFS8ORo), and the slides
@@ -22,7 +23,7 @@ on [Google Slides](https://docs.google.com/presentation/d/1VgRbiYih9ODhcPnL8dS0W
 and in [PDF](https://gitlab.com/gitlab-org/create-stage/uploads/a4fdb1026278bda5c1c5bb574379cf80/Create_Deep_Dive__Gitaly_for_Create_Ruby_Devs.pdf).
 
 Everything covered in this deep dive was accurate as of GitLab 11.11, and while specific details may
-have changed since then, it should still serve as a good introduction.
+have changed, it should still serve as a good introduction.
 
 ## Beginner's guide
 
@@ -43,7 +44,7 @@ needs direct access to the Git repository *must* be implemented in Gitaly, and
 exposed via an RPC.
 
 It's often easier to develop a new feature in Gitaly if you make the changes to
-GitLab that will use the new feature in a separate merge request, to be merged
+GitLab that intends to use the new feature in a separate merge request, to be merged
 immediately after the Gitaly one. This allows you to test your changes before
 they are merged.
 
@@ -107,9 +108,9 @@ bundle exec rake gitlab:features:disable_rugged
 Most of this code exists in the `lib/gitlab/git/rugged_impl` directory.
 
 NOTE:
-You should NOT need to add or modify code related to
-Rugged unless explicitly discussed with the [Gitaly
-Team](https://gitlab.com/groups/gl-gitaly/group_members). This code does
+You should *not* need to add or modify code related to
+Rugged unless explicitly discussed with the
+[Gitaly Team](https://gitlab.com/groups/gl-gitaly/group_members). This code does
 NOT work on GitLab.com or other GitLab instances that do not use NFS.
 
 ## `TooManyInvocationsError` errors
@@ -129,7 +130,7 @@ Isolate the source of the n+1 problem. This is normally a loop that results in G
 element in an array. If you are unable to isolate the problem, please contact a member
 of the [Gitaly Team](https://gitlab.com/groups/gl-gitaly/group_members) for assistance.
 
-Once the source has been found, wrap it in an `allow_n_plus_1_calls` block, as follows:
+After the source has been found, wrap it in an `allow_n_plus_1_calls` block, as follows:
 
 ```ruby
 # n+1: link to n+1 issue
@@ -139,7 +140,7 @@ Gitlab::GitalyClient.allow_n_plus_1_calls do
 end
 ```
 
-Once the code is wrapped in this block, this code path is excluded from n+1 detection.
+After the code is wrapped in this block, this code path is excluded from n+1 detection.
 
 ## Request counts
 
@@ -164,13 +165,13 @@ end
 Normally, GitLab CE/EE tests use a local clone of Gitaly in
 `tmp/tests/gitaly` pinned at the version specified in
 `GITALY_SERVER_VERSION`. The `GITALY_SERVER_VERSION` file supports also
-branches and SHA to use a custom commit in <https://gitlab.com/gitlab-org/gitaly>.
+branches and SHA to use a custom commit in [the repository](https://gitlab.com/gitlab-org/gitaly).
 
 NOTE:
 With the introduction of auto-deploy for Gitaly, the format of
 `GITALY_SERVER_VERSION` was aligned with Omnibus syntax.
 It no longer supports `=revision`, it evaluates the file content as a Git
-reference (branch or SHA). Only if it matches a semver does it prepend a `v`.
+reference (branch or SHA). Only if it matches a semantic version does it prepend a `v`.
 
 If you want to run tests locally against a modified version of Gitaly you
 can replace `tmp/tests/gitaly` with a symlink. This is much faster
@@ -195,7 +196,7 @@ Note that CI tests do not use your locally modified version of
 Gitaly. To use a custom Gitaly version in CI you need to update
 GITALY_SERVER_VERSION as described at the beginning of this section.
 
-To use a different Gitaly repository, e.g., if your changes are present
+To use a different Gitaly repository, such as if your changes are present
 on a fork, you can specify a `GITALY_REPO_URL` environment variable when
 running tests:
 
@@ -218,7 +219,7 @@ as a [CI environment variable](../ci/variables/README.md#gitlab-cicd-environment
 
 If you are making changes to the RPC client, such as adding a new endpoint or adding a new
 parameter to an existing endpoint, follow the guide for
-[Gitaly proto](https://gitlab.com/gitlab-org/gitaly/blob/master/proto/README.md). After pushing
+[Gitaly protobuf specifications](https://gitlab.com/gitlab-org/gitaly/blob/master/proto/README.md). After pushing
 the branch with the changes (`new-feature-branch`, for example):
 
 1. Change the `gitaly` line in the Rails' `Gemfile` to:
@@ -328,15 +329,15 @@ the integration by using GDK:
    1. Uncomment `prometheus_listen_addr` in the configuration file and run `gdk restart gitaly`.
 
 1. Make sure that the flag is not enabled yet:
-   1. Perform whatever action is required to trigger your changes (project creation,
-      submitting commit, observing history, etc.).
+   1. Perform whatever action is required to trigger your changes, such as project creation,
+      submitting commit, or observing history.
    1. Check that the list of current metrics has the new counter for the feature flag:
 
       ```shell
       curl --silent "http://localhost:9236/metrics" | grep go_find_all_tags
       ```
 
-1. Once you observe the metrics for the new feature flag and it increments, you
+1. After you observe the metrics for the new feature flag and it increments, you
    can enable the new feature:
    1. Navigate to GDK's root directory.
    1. Start a Rails console:
@@ -359,7 +360,7 @@ the integration by using GDK:
       ```
 
    1. Exit the Rails console and perform whatever action is required to trigger
-      your changes (project creation, submitting commit, observing history, etc.).
+      your changes, such as project creation, submitting commit, or observing history.
    1. Verify the feature is on by observing the metrics for it:
 
       ```shell

doc/development/integrations/jenkins.md

@@ -21,7 +21,7 @@ brew services start jenkins
 
 GitLab does not allow requests to localhost or the local network by default. When running Jenkins on your local machine, you need to enable local access.
 
-1. Log into your GitLab instance as an admin.
+1. Log into your GitLab instance as an administrator.
 1. Go to **Admin Area > Settings > Network**.
 1. Expand **Outbound requests** and check the following checkboxes:
 
@@ -32,7 +32,7 @@ GitLab does not allow requests to localhost or the local network by default. Whe
 
 Jenkins uses the GitLab API and needs an access token.
 
-1. Log in to your GitLab instance.
+1. Sign in to your GitLab instance.
 1. Click on your profile picture, then click **Settings**.
 1. Click **Access Tokens**.
 1. Create a new Access Token with the **API** scope enabled. Note the value of the token.

doc/development/integrations/jira_connect.md

@@ -19,10 +19,12 @@ The following are required to install and test the app:
   - [GDK with Gitpod](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/gitpod.md)
     documentation.
 
-  You **must not** use tunneling tools such as Serveo or `ngrok`. These are
+  You **must not** use tunneling tools such as
+  <!-- vale gitlab.Spelling = NO --> Serveo <!-- vale gitlab.Spelling = YES -->
+  or `ngrok`. These are
   security risks, and must not be run on developer laptops.
 
-  Jira requires all connections to the app host to be over SSL, so if you set up
+  Jira requires all connections to the app host to be over SSL. If you set up
   your own environment, remember to enable SSL and an appropriate certificate.
 
 ## Install the app in Jira

doc/development/internal_api.md

@@ -51,7 +51,7 @@ POST /internal/allowed
 | `key_id`  | string | no       | ID of the SSH-key used to connect to GitLab Shell |
 | `username` | string | no      | Username from the certificate used to connect to GitLab Shell |
 | `project`  | string | no (if `gl_repository` is passed) | Path to the project |
-| `gl_repository`  | string | no (if `project` is passed) | Repository identifier (e.g. `project-7`) |
+| `gl_repository`  | string | no (if `project` is passed) | Repository identifier, such as `project-7` |
 | `protocol` | string | yes     | SSH when called from GitLab Shell, HTTP or SSH when called from Gitaly |
 | `action`   | string | yes     | Git command being run (`git-upload-pack`, `git-receive-pack`, `git-upload-archive`) |
 | `changes`  | string | yes     | `<oldrev> <newrev> <refname>` when called from Gitaly, the magic string `_any` when called from GitLab Shell |
@@ -413,7 +413,7 @@ connection for the requested project. GitLab `kas` uses this to configure
 the agent to fetch Kubernetes resources from the project repository to
 sync.
 
-Only public projects are currently supported. For private projects, the ability for the
+Only public projects are supported. For private projects, the ability for the
 agent to be authorized is [not yet implemented](https://gitlab.com/gitlab-org/gitlab/-/issues/220912).
 
 | Attribute | Type   | Required | Description |
@@ -456,7 +456,7 @@ Cluster.
 
 | Attribute | Type   | Required | Description |
 |:----------|:-------|:---------|:------------|
-| `alert` | Hash | yes | Alerts detail. Currently same format as [3rd party alert](../operations/incident_management/alert_integrations.md#customize-the-alert-payload-outside-of-gitlab). |
+| `alert` | Hash | yes | Alerts detail. Same format as [3rd party alert](../operations/incident_management/alert_integrations.md#customize-the-alert-payload-outside-of-gitlab). |
 
 ```plaintext
 POST internal/kubernetes/modules/cilium_alert

doc/development/lfs.md

@@ -9,13 +9,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 ## Deep Dive
 
 In April 2019, Francisco Javier López hosted a Deep Dive (GitLab team members only: `https://gitlab.com/gitlab-org/create-stage/issues/1`)
-on the GitLab [Git LFS](../topics/git/lfs/index.md) implementation to share his domain
-specific knowledge with anyone who may work in this part of the codebase in the future.
+on the GitLab [Git LFS](../topics/git/lfs/index.md) implementation to share domain-specific
+knowledge with anyone who may work in this part of the codebase in the future.
 You can find the <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> [recording on YouTube](https://www.youtube.com/watch?v=Yyxwcksr0Qc),
 and the slides on [Google Slides](https://docs.google.com/presentation/d/1E-aw6-z0rYd0346YhIWE7E9A65zISL9iIMAOq2zaw9E/edit)
 and in [PDF](https://gitlab.com/gitlab-org/create-stage/uploads/07a89257a140db067bdfb484aecd35e1/Git_LFS_Deep_Dive__Create_.pdf).
-Everything covered in this deep dive was accurate as of GitLab 11.10, and while specific
-details may have changed since then, it should still serve as a good introduction.
+This deep dive was accurate as of GitLab 11.10, and while specific
+details may have changed, it should still serve as a good introduction.
 
 ## Including LFS blobs in project archives
 
@@ -52,7 +52,7 @@ JSON payload prefaced with `git-archive`. This payload includes the
 archive already exists in the archive cache, Workhorse sends that
 file. Otherwise, Workhorse sends the `SendArchiveRequest` to the
 appropriate Gitaly server.
-1. The Gitaly server will call `git archive <ref>` to begin generating
+1. The Gitaly server calls `git archive <ref>` to begin generating
 the Git archive on-the-fly. If the `include_lfs_blobs` flag is enabled,
 Gitaly enables a custom LFS smudge filter via the `-c
 filter.lfs.smudge=/path/to/gitaly-lfs-smudge` Git option.
@@ -76,7 +76,7 @@ process, which writes the contents to the standard output.
 1. The archive data is sent back to the client.
 
 In step 7, the `gitaly-lfs-smudge` filter must talk to Workhorse, not to
-Rails, or an invalid LFS blob will be saved. To support this, GitLab
+Rails, or an invalid LFS blob is saved. To support this, GitLab
 13.5 [changed the default Omnibus configuration to have Gitaly talk to
 the Workhorse](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/4592)
 instead of Rails.
@@ -84,6 +84,6 @@ instead of Rails.
 One side effect of this change: the correlation ID of the original
 request is not preserved for the internal API requests made by Gitaly
 (or `gitaly-lfs-smudge`), such as the one made in step 8. The
-correlation IDs for those API requests will be random values until [this
+correlation IDs for those API requests are random values until [this
 Workhorse issue](https://gitlab.com/gitlab-org/gitlab-workhorse/-/issues/309) is
 resolved.

doc/development/new_fe_guide/modules/widget_extensions.md

@@ -10,13 +10,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 ## Summary
 
-Extensions in the merge request widget allow for others team to quickly and easily add new features
-into the widget that will match the existing design and interaction as other extensions.
+Extensions in the merge request widget enable you to add new features
+into the widget that match the existing design and interaction as other extensions.
 
 ## Usage
 
-To use extensions you need to first create a new extension object that will be used to fetch the
-data that will be rendered in the extension. See the example file in
+To use extensions you need to first create a new extension object to fetch the
+data to render in the extension. See the example file in
 `app/assets/javascripts/vue_merge_request_widget/extensions/issues.js` for a working example.
 
 The basic object structure is as below:
@@ -36,8 +36,8 @@ export default {
 };
 ```
 
-Following the same data structure allows each extension to follow the same registering structure
-but allows for each extension to manage where it gets its own data from.
+By following the same data structure, each extension can follow the same registering structure,
+but each extension can manage its data sources.
 
 After creating this structure you need to register it. Registering the extension can happen at any
 point _after_ the widget has been created.

doc/development/wikis.md

@@ -12,8 +12,8 @@ description: "GitLab's development guidelines for Wikis"
 
 ## Overview
 
-The wiki functionality in GitLab is based on [Gollum 4.x](https://github.com/gollum/gollum/),
-which is used in [Gitaly's](gitaly.md) Ruby service and accessed from the Rails app through Gitaly RPC calls.
+The wiki functionality in GitLab is based on [Gollum 4.x](https://github.com/gollum/gollum/).
+It's used in [Gitaly's](gitaly.md) Ruby service, and accessed from the Rails app through Gitaly RPC calls.
 
 Wikis use Git repositories as storage backend, and can be accessed through:
 
@@ -43,7 +43,7 @@ When rendering wiki pages, we don't use Gollum at all and instead go through a
 [custom Banzai pipeline](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/banzai/pipeline/wiki_pipeline.rb).
 This adds some [wiki-specific markup](../user/markdown.md#wiki-specific-markdown), such as Gollum's `[[link]]` syntax.
 
-Since we do not make use of most of Gollum's features, we plan to move away from it entirely at some point.
+Because we do not make use of most of Gollum's features, we plan to move away from it entirely at some point.
 [See this epic](https://gitlab.com/groups/gitlab-org/-/epics/2381) for reference.
 
 ## Model classes