Merge branch 'vale-substitution-fixes-8-13-21' into 'master'

Vale substitution fixes in user documentation

See merge request gitlab-org/gitlab!68222

doc/integration/gitpod.md

@@ -52,7 +52,7 @@ For GitLab self-managed instances, a GitLab administrator needs to:
    1. Add your Gitpod instance URL (for example, `https://gitpod.example.com`).
    1. Select the **Save changes** button.
 
-Your users then need to [enable it for themselves](#enable-gitpod-in-your-user-settings).
+Your users can then [enable it for themselves](#enable-gitpod-in-your-user-settings).
 
 ## Launch Gitpod in GitLab
 

doc/update/mysql_to_postgresql.md

@@ -52,7 +52,7 @@ For other distributions, follow the instructions in PostgreSQL's
 and then install `pgloader`.
 
 If you are migrating to a Docker based installation, you must install
-pgLoader within the container as it is not included in the container image.
+pgLoader in the container as it is not included in the container image.
 
 1. Start a shell session in the context of the running container:
 
@@ -70,7 +70,7 @@ pgLoader within the container as it is not included in the container image.
 ## Omnibus GitLab installations
 
 For [Omnibus GitLab packages](https://about.gitlab.com/install/), you first
-need to enable the bundled PostgreSQL:
+enable the bundled PostgreSQL:
 
 1. Stop GitLab:
 
@@ -283,7 +283,7 @@ Sometimes, you might encounter some errors during or after the migration.
 
 ### Database error permission denied
 
-The PostgreSQL user that you use for the migration MUST have **superuser** privileges.
+The PostgreSQL user that you use for the migration **must** have **superuser** privileges.
 Otherwise, you may see a similar message to the following:
 
 ```plaintext
@@ -295,7 +295,7 @@ debugger invoked on a CL-POSTGRES-ERROR:INSUFFICIENT-PRIVILEGE in thread
     QUERY: ALTER TABLE approver_groups DISABLE TRIGGER ALL;
 ```
 
-### Experiencing 500 errors after the migration
+### 500 errors after the migration
 
 If you experience 500 errors after the migration, try to clear the cache:
 

doc/update/restore_after_failure.md

@@ -13,7 +13,7 @@ However, it's important to know how to recover when problems do arise.
 
 In some cases after a failed upgrade, the fastest solution is to roll back to
 the previous version you were using. We recommend this path because the failed
-upgrade will likely have made database changes that can not be readily reverted.
+upgrade might have made database changes that cannot be readily reverted.
 
 First, roll back the code or package. For source installations this involves
 checking out the older version (branch or tag). For Omnibus installations this
@@ -33,7 +33,7 @@ older backup it can lead to migration failures on future upgrades.
 
 Starting in GitLab 8.6 we drop all tables prior to importing the backup to
 prevent this problem. If you've restored a backup to a version prior to 8.6 you
-may need to manually correct the problem next time you upgrade.
+may have to manually correct the problem next time you upgrade.
 
 Example error:
 
@@ -49,8 +49,8 @@ PG::DuplicateTable: ERROR:  relation "lfs_objects" already exists
 Copy the version from the error. In this case the version number is
 `20151103134857`.
 
->**WARNING:** Use the following steps only if you are certain this is what you
-need to do.
+WARNING:
+Use the following steps only if you are certain you must do them.
 
 ### GitLab 8.6+
 
@@ -65,9 +65,8 @@ sudo -u git -H bundle exec rake gitlab:db:mark_migration_complete[20151103134857
 sudo gitlab-rake gitlab:db:mark_migration_complete[20151103134857]
 ```
 
-Once the migration is successfully marked, run the Rake `db:migrate` task again.
-You might need to repeat this process several times until all failed
-migrations are marked complete.
+After the migration is successfully marked, run the Rake `db:migrate` task again.
+Repeat this process until all failed migrations are complete.
 
 ### GitLab < 8.6
 
@@ -86,6 +85,5 @@ ActiveRecord::Base.connection.execute("INSERT INTO schema_migrations (version) V
 exit
 ```
 
-Once the migration is successfully marked, run the Rake `db:migrate` task again.
-You might need to repeat this process several times until all failed
-migrations are marked complete.
+After the migration is successfully marked, run the Rake `db:migrate` task again.
+Repeat this process until all failed migrations are complete.

doc/update/upgrading_from_source.md

@@ -12,12 +12,10 @@ Users wishing to upgrade to 12.0.0 must take some extra steps. See the
 version specific upgrade instructions for 12.0.0 for more details.
 
 Make sure you view this update guide from the branch (version) of GitLab you
-would like to install (e.g., `11.8`. You can select the version in the version
-dropdown at the top left corner of GitLab (below the menu bar).
+would like to install (for example, `11.8`). You can select the required version of documentation in the dropdown at the top right corner of GitLab documentation page.
 
-In all examples, replace `BRANCH` with the branch for the version you upgrading
-to (e.g. `11-8-stable` for `11.8`), and replace `PREVIOUS_BRANCH` with the
-branch for the version you are upgrading from (e.g. `11-7-stable` for `11.7`).
+In each of the following examples, replace `BRANCH` with the branch of the version you upgrading to (for example, `11-8-stable` for `11.8`). Replace `PREVIOUS_BRANCH` with the
+branch for the version you are upgrading from (for example, `11-7-stable` for `11.7`).
 
 If the highest number stable branch is unclear please check the
 [GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation
@@ -29,7 +27,7 @@ the [Upgrading from CE to EE](upgrading_from_ce_to_ee.md) documentation.
 ## Upgrading to a new major version
 
 Major versions are reserved for backwards incompatible changes. We recommend that
-you first upgrade to the latest available minor version within your major version.
+you first upgrade to the latest available minor version of your current major version.
 Please follow the [Upgrade Recommendations](../policy/maintenance.md#upgrade-recommendations)
 to identify the ideal upgrade path.
 
@@ -152,7 +150,7 @@ WARNING:
 From GitLab 14.0, you must use at least PostgreSQL 12.
 
 The latest version of GitLab might depend on a more recent PostgreSQL version
-than what you're currently running. You may also need to enable some
+than what you are running. You may also have to enable some
 extensions. For more information, see the
 [PostgreSQL requirements](../install/requirements.md#postgresql-requirements)
 
@@ -212,9 +210,9 @@ git diff origin/PREVIOUS_BRANCH:lib/support/nginx/gitlab-ssl origin/BRANCH:lib/s
 git diff origin/PREVIOUS_BRANCH:lib/support/nginx/gitlab origin/BRANCH:lib/support/nginx/gitlab
 ```
 
-If you are using Strict-Transport-Security in your installation to continue
-using it you must enable it in your NGINX configuration as GitLab application no
-longer handles setting it.
+If you are using Strict-Transport-Security in your installation, you must enable it in your
+NGINX configuration to continue using it. This is because the GitLab application no longer
+sets it.
 
 If you are using Apache instead of NGINX see the updated [Apache templates](https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache).
 Also note that because Apache does not support upstreams behind Unix sockets you
@@ -391,11 +389,11 @@ cp config/initializers/rack_attack.rb config/initializers/rack_attack_backup.rb
 
 ### 1. Revert the code to the previous version
 
-To revert to a previous version, you need to follow the upgrading guides
+To revert to a previous version, you must follow the upgrading guides
 for the previous version.
 
 For example, if you have upgraded to GitLab 12.6 and want to revert back to
-12.5, you need to follow the guides for upgrading from 12.4 to 12.5. You can
+12.5, follow the guides for upgrading from 12.4 to 12.5. You can
 use the version dropdown at the top of the page to select the right version.
 
 When reverting, you should **not** follow the database migration guides, as the