Mark's updatesdocs/autodevops-cleanup

1 files changed, 38 insertions, 32 deletions

diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md
index 98e46b43408..75ad3035cfb 100644
--- a/doc/topics/autodevops/index.md
+++ b/doc/topics/autodevops/index.md
@@ -13,7 +13,7 @@ With Auto DevOps, the software development process becomes easier to set up
 as every project can have a complete workflow from build to deploy and monitoring,
 with minimal to zero configuration.
 
-Comprised of a set of stages, Auto DevOps brings the best practices to your
+Comprised of a set of stages, Auto DevOps brings these best practices to your
 project in an easy and default way:
 
 1. [Auto Build](#auto-build)
@@ -33,7 +33,7 @@ knowledge of the following:
 - [Prometheus](https://prometheus.io/docs/introduction/overview/)
 
 TIP: **Tip:**
-Auto DevOps provides some defaults for all the stages, you can, however,
+Auto DevOps provides great defaults for all the stages. You can, however,
 [customize](#customizing) almost everything to your needs.
 
 ## Prerequisites
@@ -43,13 +43,12 @@ installed in the cluster to make full use of Auto DevOps. If you do not have
 Kubernetes or Prometheus installed, then Auto Review Apps, Auto Deploy, and Auto
 Monitoring will be silently skipped.
 
-In the table below, you can see the prerequisites for each stage in a summary.
-Read below for details of each prerequisite as well as in the section of each
-stage.
+In the table below, you can see the prerequisites for each stage.
+Read below for details of each.
 
 | **Stage** | **Requirements** |
 | --------- | ---------------- |
-| [Auto Build](#auto-build)               | 1) A `Dockerfile` at the root directory of your repository, 2) GitLab Runner with Kubernetes or Docker executor. |
+| [Auto Build](#auto-build)               | 1) GitLab Runner with Kubernetes or Docker executor. |
 | [Auto Test](#auto-test)                 | 1) A test suite for the language/framework of the project, 2) GitLab Runner with Kubernetes or Docker executor. |
 | [Auto Code Quality](#auto-code-quality) | GitLab Runner with Kubernetes or Docker executor. |
 | [Auto Review Apps](#auto-review-apps)   | 1) Kubernetes cluster, 2) GitLab Runner with Kubernetes or Docker executor, 3) base domain set up, 4) Kubernetes integration enabled. |
@@ -89,7 +88,7 @@ with GitLab.com, then you should take these prerequisites into account:
     1. **Wildcard TLS termination** - You can deploy the
        [`kube-lego`](https://github.com/kubernetes/charts/tree/master/stable/kube-lego)
        Helm chart to your Kubernetes cluster to automatically issue certificates
-       for your domains by Let's Encrypt.
+       for your domains using Let's Encrypt.
 1. **Prometheus** - To enable Auto Monitoring, you will need Prometheus installed
    somewhere (inside or outside your cluster) and configured to scrape your
    Kubernetes cluster. To get response metrics (in addition to system metrics),
@@ -104,24 +103,26 @@ with GitLab.com, then you should take these prerequisites into account:
 The Auto DevOps base domain is required if you want to make use of [Auto
 Review Apps](#auto-review-apps) and [Auto Deploy](#auto-deploy). It is defined
 under the project's CI/CD settings while [enabling Auto DevOps](#enabling-auto-devops).
+It can also be set at the project or group level as a variable, `AUTO_DEVOPS_DOMAIN`.
 
-A wildcard DNS A record is required, for example:
+A wildcard DNS A record matching the base domain is required, for example,
+given a base domain of `example.com`, you'd need a DNS entry like:
 
 ```
 *.example.com   3600     A     1.2.3.4
 ```
 
-where `example.com` the domain name under which the deployed apps will be served,
-and `1.2.3.4` the IP of your load balancer, generally NGINX ingress
+where `example.com` is the domain name under which the deployed apps will be served,
+and `1.2.3.4` is the IP address of your load balancer; generally NGINX
 ([see prerequisites](#prerequisites)). How to set up the DNS record is beyond
-the scope of this document, you should check with your DNS provider.
+the scope of this document; you should check with your DNS provider.
 
-Once set up, all requests will hit the load balancer which in turn will route
+Once set up, all requests will hit the load balancer, which in turn will route
 them to the Kubernetes pods that run your application(s).
 
 NOTE: **Note:**
-If GitLab is installed using the [GitLab Omnibus Helm Chart] there are two
-options: provide a static IP, or have one assigned. For more info check the
+If GitLab is installed using the [GitLab Omnibus Helm Chart], there are two
+options: provide a static IP, or have one assigned. For more information see the
 relevant docs on the [network prerequisites](../../install/kubernetes/gitlab_omnibus.md#networking-prerequisites).
 
 ## Quick start
@@ -140,11 +141,11 @@ full use of Auto DevOps. If this is your fist time, we recommend you follow the
 1. Go to your project's **Settings > CI/CD > General pipelines settings** and
    find the Auto DevOps section
 1. Select "Enable Auto DevOps"
-1. Optionally but recommended, add in the [base domain](#auto-devops-base-domain)
+1. Optionally, but recommended, add in the [base domain](#auto-devops-base-domain)
    that will be used by Kubernetes to deploy your application
 1. Hit **Save changes** for the changes to take effect
 
-Now that it's enabled, there's a few steps more depending whether your project
+Now that it's enabled, there are a few more steps depending on whether your project
 has a `.gitlab-ci.yml` or not:
 
 - **For projects with no `.gitlab-ci.yml` present:**
@@ -152,8 +153,8 @@ has a `.gitlab-ci.yml` or not:
   repository or manually visiting `https://example.gitlab.com/<username>/<project>/pipelines/new`
   and creating a new pipeline for your default branch, generally `master`.
 - **For projects with a `.gitlab-ci.yml` present:**
-  All you need to do is either remove your existing `.gitlab-ci.yml` or
-  [customize it](#customizing-gitlab-ci-yml) to your liking.
+  All you need to do is remove your existing `.gitlab-ci.yml`, and you can even
+  do that in a branch to test Auto DevOps before committing to `master`.
 
 ## Stages of Auto DevOps
 
@@ -170,12 +171,12 @@ Auto Build creates a build of the application in one of two ways:
   to automatically detect and build the application into a Docker image.
 
 Either way, the resulting Docker image is automatically pushed to the
-[Container Registry][container-registry], tagged with the commit SHA.
+[Container Registry][container-registry] and tagged with the commit SHA.
 
 CAUTION: **Important:**
 If you are also using Auto Review Apps and Auto Deploy and choose to provide
 your own `Dockerfile`, make sure you expose your application to port
-`5000` as this is the one used by default and picked by Kubernetes.
+`5000` as this is the port assumed by the default Helm chart.
 
 ### Auto Test
 
@@ -188,7 +189,7 @@ you may succeed with a [custom buildpack](#custom-buildpack). Check the
 [currently supported languages](#currently-supported-languages).
 
 NOTE: **Note:**
-Auto Test uses tests you already have them in your application. If there are no
+Auto Test uses tests you already have in your application. If there are no
 tests, it's up to you to add them.
 
 ### Auto Code Quality
@@ -196,8 +197,8 @@ tests, it's up to you to add them.
 Auto Code Quality uses the open source
 [`codeclimate` image](https://hub.docker.com/r/codeclimate/codeclimate/) to run
 static analysis and other code checks on the current code. The report is
-created and is uploaded as an artifact which you can later download and check
-it out. In GitLab Enterprise Edition Starter, differences between the source and
+created, and is uploaded as an artifact which you can later download and check
+out. In GitLab Enterprise Edition Starter, differences between the source and
 target branches are
 [shown in the merge request widget](https://docs.gitlab.com/ee/user/project/merge_requests/code_quality_diff.html).
 
@@ -259,7 +260,7 @@ get system metrics such as CPU and memory usage directly from
 and response metrics such as HTTP error rates, latency, and throughput from the
 [NGINX server](../../user/project/integrations/prometheus_library/nginx_ingress.md).
 
-Some of the metrics include:
+The metrics include:
 
 - **Response Metrics:** latency, throughput, error rate
 - **System Metrics:** CPU utilization, memory utilization
@@ -284,8 +285,8 @@ To view the metrics, open the
 
 ## Customizing
 
-While Auto DevOps provides some defaults to get you started, you can customize
-almost everything to fit your needs. From custom [buildpacks](#custom-buildpacks),
+While Auto DevOps provides great defaults to get you started, you can customize
+almost everything to fit your needs; from custom [buildpacks](#custom-buildpacks),
 to [`Dockerfile`s](#custom-dockerfile), [Helm charts](#custom-helm-chart), or
 even copying the complete [CI/CD configuration](#customizing-gitlab-ci-yml)
 into your project to enable staging and canary deployments, and more.
@@ -382,6 +383,11 @@ Set up the replica variables using a
 and scale your application by just redeploying it. That way, you don't have to
 change something in your repository to trigger a new deployment!
 
+NOTE: **Note:**
+You should *not* scale your application using Kubernetes directly. This can
+cause confusion with Helm not detecting the change, and subsequent deploys with
+Auto DevOps can undo your changes.
+
 #### PostgreSQL variables
 
 PostgreSQL can be customized with the following variables.
@@ -404,12 +410,12 @@ following variable.
 
 #### Advanced replica variables setup
 
-Apart from the two [replica-related variables](#helm-chart-variables) that are
-automatically set up by Auto Deploy, you can also set your own.
+Apart from the two [replica-related variables](#helm-chart-variables) for
+production mentioned above, you can also use others for different environments.
 
 There's a very specific mapping between Kubernetes' label named `track`,
 GitLab CI/CD environment names, and the replicas environment variable.
-The generic rule applies: `TRACK_ENV_REPLICAS`. Where:
+The general rule is: `TRACK_ENV_REPLICAS`. Where:
 
 - `TRACK`: The capitalized value of the `track`
   [Kubernetes label](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)
@@ -421,8 +427,8 @@ The generic rule applies: `TRACK_ENV_REPLICAS`. Where:
 That way, you can define your own `TRACK_ENV_REPLICAS` variables with which
 you will be able to scale the pod's replicas easily.
 
-In the example below, the environment's name is `qa` which would result to the
-`QA_REPLICAS` environment variable:
+In the example below, the environment's name is `qa` which would result in
+looking for the `QA_REPLICAS` environment variable:
 
 ```yaml
 QA testing:
@@ -503,7 +509,7 @@ for a successful initial deployment.
 
 After the pipeline completes, Kubernetes will no longer be able to access the
 Container Registry. **Restarting a pod, scaling a service, or other actions which
-require on-going access to the registry will fail**. On-going secure access is
+require on-going access to the registry may fail**. On-going secure access is
 planned for a subsequent release.
 
 ## Troubleshooting