Reword note about familiarity with k8s

4 files changed, 39 insertions, 48 deletions

diff --git a/doc/install/README.md b/doc/install/README.md
index 9a96ab82cf0..8eca5d3f164 100644
--- a/doc/install/README.md
+++ b/doc/install/README.md
@@ -6,17 +6,7 @@ description: Read through the GitLab installation methods.
 # Installation
 
 GitLab can be installed in most GNU/Linux distributions and in a number
-of cloud providers.
-
-## Requirements
-
-Before installing GitLab, make sure to check the [requirements documentation](requirements.md)
-which includes useful information on the supported Operating Systems as well as
-the hardware requirements.
-
-## Installation methods
-
-To get the best experience from GitLab you need to balance:
+of cloud providers. To get the best experience from GitLab you need to balance:
 
 1. Performance
 1. Reliability
@@ -29,44 +19,44 @@ Our Omnibus GitLab packages are mature, scalable, support
 today on GitLab.com. Our Helm charts are recommended for those who are familiar
 with Kubernetes.
 
-### Install GitLab using the Omnibus GitLab package (recommended)
+## Requirements
 
-This installation method [uses the Omnibus GitLab package](https://about.gitlab.com/install/),
-using our official deb/rpm repositories. This is the recommended way.
+Before installing GitLab, make sure to check the [requirements documentation](requirements.md)
+which includes useful information on the supported Operating Systems as well as
+the hardware requirements.
+
+## Install GitLab using the Omnibus GitLab package (recommended)
+
+This installation method uses the Omnibus GitLab package, using our official
+deb/rpm repositories. This is the recommended way.
 
 If you need additional flexibility and resilience, we recommend deploying
 GitLab as described in our [High Availability documentation](../administration/high_availability/README.md).
 
+[**> Install GitLab using the Omnibus GitLab package.**](https://about.gitlab.com/install/)
+
 ### Alternative to Omnibus GitLab
 
 If the GitLab Omnibus package is not available in your distribution, you can
 choose between:
 
-- [Installation from source](installation.md): Install GitLab from source.
-  Useful for unsupported systems like *BSD. For an overview of the directory
-  structure, read the [structure documentation](structure.md).
-  While the recommended database is PostgreSQL, we provide information to install
-  GitLab [using MySQL](database_mysql.md).
-- [Docker](docker.md): Install Omnibus GitLab using Docker.
+- [Installing GitLab from source](installation.md): Useful for unsupported
+  systems like *BSD. For an overview of the directory structure, read the
+  [structure documentation](structure.md). While the recommended database is
+  PostgreSQL, we provide information to install GitLab
+  [using MySQL](database_mysql.md).
+- [Installing Omnibus GitLab using Docker](docker.md).
 
-### Install GitLab on Kubernetes via the GitLab Helm charts
+## Install GitLab on Kubernetes via the GitLab Helm charts
 
-NOTE: **If in doubt, choose Omnibus:**
+NOTE: **Kubernetes experience required:**
 We recommend being familiar with Kubernetes before using it to deploy GitLab in
 production. The methods for management, observability, and some concepts are
 different than traditional deployments.
 
-GitLab is committed to Kubernetes as a foundational technology. There are three
-areas where Kubernetes intersects with GitLab:
-
-1. Deploying your applications from GitLab projects to Kubernetes (e.g., see [Auto DevOps](../topics/autodevops/index.md)).
-1. [Running GitLab CI/CD Runners in a Kubernetes Cluster](https://docs.gitlab.com/runner/install/kubernetes.html).
-1. Installing GitLab in Kubernetes.
-
-While we recommend using GitLab for the first two points above, for most scenarios
-we do not currently recommend installing GitLab in Kubernetes. There are a number
-of trade-offs that you need to be aware of that may not be immediately obvious
-and could prevent you getting the best experience from GitLab:
+When installing GitLab on kubernetes, there are a number of trade-offs that you
+need to be aware of that may not be immediately obvious and could prevent you
+getting the best experience from GitLab:
 
 - Configuration of features such as object storage and backups can be more challenging.
 - Administration and troubleshooting requires Kubernetes knowledge.
@@ -75,10 +65,9 @@ and could prevent you getting the best experience from GitLab:
   are deployed in a redundant fashion.
 - There are some feature [limitations to be aware of](kubernetes/gitlab_chart.md#limitations).
 
-If you're happy with the trade-offs, you can use our official Helm charts to get
-started and [install GitLab in Kubernetes](kubernetes/index.md).
+[**> Install GitLab on Kubernetes using the GitLab Helm charts.**](kubernetes/index.md)
 
-### Install GitLab on cloud providers
+## Install GitLab on cloud providers
 
 GitLab can be installed on a variety of cloud providers:
 
diff --git a/doc/install/docker.md b/doc/install/docker.md
index c7dc9db70c5..d0129f0f5c4 100644
--- a/doc/install/docker.md
+++ b/doc/install/docker.md
@@ -7,9 +7,10 @@ GitLab provides official Docker images to allowing you to easily take advantage
 ## Omnibus GitLab based images
 
 GitLab maintains a set of [official Docker images](https://hub.docker.com/r/gitlab) based on our [Omnibus GitLab package](https://docs.gitlab.com/omnibus/README.html). These images include:
-* [GitLab Community Edition](https://hub.docker.com/r/gitlab/gitlab-ce/)
-* [GitLab Enterprise Edition](https://hub.docker.com/r/gitlab/gitlab-ee/)
-* [GitLab Runner](https://hub.docker.com/r/gitlab/gitlab-runner/)
+
+- [GitLab Community Edition](https://hub.docker.com/r/gitlab/gitlab-ce/)
+- [GitLab Enterprise Edition](https://hub.docker.com/r/gitlab/gitlab-ee/)
+- [GitLab Runner](https://hub.docker.com/r/gitlab/gitlab-runner/)
 
 A [complete usage guide](https://docs.gitlab.com/omnibus/docker/) to these images is available, as well as the [Dockerfile used for building the images](https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master/docker).
 
diff --git a/doc/install/kubernetes/gitlab_chart.md b/doc/install/kubernetes/gitlab_chart.md
index 316eb788009..85fa04731eb 100644
--- a/doc/install/kubernetes/gitlab_chart.md
+++ b/doc/install/kubernetes/gitlab_chart.md
@@ -1,13 +1,13 @@
 # GitLab Helm Chart
 
 This is the official way to install GitLab on a cloud native environment.
-For more information on other available GitLab Helm Charts, see the [charts overview](index.md#chart-overview).
 
-TIP: **If in doubt, choose Omnibus GitLab:**
-Our [Omnibus GitLab packages](../README.md#install-gitlab-using-the-omnibus-gitlab-package-recommended)
+NOTE: **Kubernetes experience required:**
+Our Helm charts are recommended for those who are familiar with Kubernetes.
+If you're not sure if Kubernetes is for you, our
+[Omnibus GitLab packages](../README.md#install-gitlab-using-the-omnibus-gitlab-package-recommended)
 are mature, scalable, support [high availability](../../administration/high_availability/README.md)
-and are used today on GitLab.com. Our Helm charts are recommended for those who
-are familiar with Kubernetes.
+and are used today on GitLab.com.
 
 ## Introduction
 
diff --git a/doc/install/kubernetes/index.md b/doc/install/kubernetes/index.md
index baa37f2b495..37f5451b792 100644
--- a/doc/install/kubernetes/index.md
+++ b/doc/install/kubernetes/index.md
@@ -4,11 +4,12 @@ description: 'Read through the different methods to deploy GitLab on Kubernetes.
 
 # Installing GitLab on Kubernetes
 
-TIP: **If in doubt, choose Omnibus GitLab:**
-Our [Omnibus GitLab packages](../README.md#install-gitlab-using-the-omnibus-gitlab-package-recommended)
+NOTE: **Kubernetes experience required:**
+Our Helm charts are recommended for those who are familiar with Kubernetes.
+If you're not sure if Kubernetes is for you, our
+[Omnibus GitLab packages](../README.md#install-gitlab-using-the-omnibus-gitlab-package-recommended)
 are mature, scalable, support [high availability](../../administration/high_availability/README.md)
-and are used today on GitLab.com. Our Helm charts are recommended for those who
-are familiar with Kubernetes.
+and are used today on GitLab.com.
 
 The easiest method to deploy GitLab on [Kubernetes](https://kubernetes.io/) is
 to take advantage of GitLab's Helm charts. [Helm](https://github.com/kubernetes/helm/blob/master/README.md)