Merge branch 'eread/refactor-gitpod-docs' into 'master'

Refactor Gitpod docs

See merge request gitlab-org/gitlab!52054

doc/.vale/gitlab/spelling-exceptions.txt

@@ -167,6 +167,7 @@ GitHub
 GitLab
 gitlabsos
 Gitleaks
+Gitpod
 Gitter
 globals
 Gmail

doc/integration/gitpod.md

@@ -10,45 +10,55 @@ info: "To determine the technical writer assigned to the Stage/Group associated
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/228893) in GitLab 13.4.
 > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/258206) in GitLab 13.8
 
-With [Gitpod](https://gitpod.io/) you can describe your dev environment as code to get fully set
-up, compiled, and tested dev environments for any GitLab project. The dev environments are not only
-automated but also prebuilt which means that Gitpod continuously builds your Git branches like a CI
-server. By that you don’t have to wait for dependencies to be downloaded and builds to finish, but
-you can start coding immediately.
+With [Gitpod](https://gitpod.io/) you can describe your development environment as code to get fully
+set up, compiled, and tested development environments for any GitLab project. The development
+environments are not only automated but also prebuilt which means that Gitpod continuously builds
+your Git branches like a CI/CD server.
 
-In short: With Gitpod you can start coding instantly on any project, branch, and merge request from
-any device, at any time.
+This means you don't have to wait for dependencies to be downloaded and builds to finish, you can start
+coding immediately. With Gitpod you can start coding instantly on any project, branch, and merge
+request from any device, at any time.
 
-![Gitpod interface](img/gitpod_web_interface_v13_4.png)
+To use the GitLab Gitpod integration, it must be enabled for your GitLab instance. Users of:
 
-You can launch Gitpod directly from GitLab by clicking the **Gitpod** button from the **Web IDE**
-dropdown on the project page:
-
-![Gitpod Button on Project Page](img/gitpod_button_project_page_v13_4.png)
+- GitLab.com can use it immediately after it's [enabled in their user settings](#enable-gitpod-in-your-user-settings).
+- GitLab self-managed instances can use it after:
+  1. It's [enabled and configured by a GitLab administrator](#configure-a-self-managed-instance).
+  1. It's [enabled in their user settings](#enable-gitpod-in-your-user-settings).
 
 To learn more about Gitpod, see their [features](https://www.gitpod.io/features/) and
 [documentation](https://www.gitpod.io/docs/).
 
-To use the GitLab-Gitpod integration, you need to enable it from your user preferences:
+## Enable Gitpod in your user settings
+
+With the Gitpod integration enabled for your GitLab instance, to enable it for yourself:
+
+1. Select your avatar in the top-right corner, then select **Settings > Preferences**.
+1. Under **Integrations**, locate the **Gitpod** section.
+1. Check the **Enable Gitpod integration** checkbox and select the **Save changes** button.
 
-1. From the GitLab UI, click your avatar in the top-right corner, then click **Settings**.
-1. On the left-hand nav, click **Preferences**.
-1. Under **Integrations**, find the **Gitpod** section.
-1. Check **Enable Gitpod**.
+## Configure a self-managed instance **(CORE ONLY)**
 
-Users of GitLab.com can enable it and start using straightaway. Users of GitLab self-managed instances
-can follow the same steps once the integration has been enabled and configured by a GitLab administrator.
+For GitLab self-managed instances, a GitLab administrator needs to:
 
-## Configure your GitLab instance with Gitpod **(CORE ONLY)**
+1. Set up a Gitpod instance to integrate with GitLab. Refer to the [Gitpod documentation](https://www.gitpod.io/docs/self-hosted/latest/self-hosted/)
+   to get your instance up and running.
+1. Enable it in GitLab:
+   1. Go to **Admin Area > Settings > General**.
+   1. Expand the **Gitpod** configuration section.
+   1. Check the **Enable Gitpod integration** checkbox.
+   1. Add your Gitpod instance URL (for example, `https://gitpod.example.com`).
+   1. Select the **Save changes** button.
 
-The integration of Gitpod with GitLab is enabled on GitLab.com and available to all users.
-For GitLab self-managed instances, a GitLab administrator needs to enable it through the admin settings.
+Your users then need to [enable it for themselves](#enable-gitpod-in-your-user-settings).
 
-First, you (GitLab admin) need to set up a Gitpod instance to integrate with GitLab.
-Head over to the [Gitpod documentation](https://www.gitpod.io/docs/self-hosted/latest/self-hosted/) to
-get your instance up and running. Once done:
+## Launch Gitpod in GitLab
 
-1. In GitLab, go to **Admin Area > Settings > General**.
-1. Expand the **Gitpod** configuration section.
-1. Check **Enable Gitpod**.
-1. Add your Gitpod instance URL (for example, `https://gitpod.example.com`).
+You can launch Gitpod directly from GitLab by clicking the **Gitpod** button from the **Web IDE**
+dropdown on the project page:
+
+![Gitpod Button on Project Page](img/gitpod_button_project_page_v13_4.png)
+
+A project launched in GitLab looks like:
+
+![Gitpod interface](img/gitpod_web_interface_v13_4.png)