More cleanup for Auto DevOps docs

- More info for the prerequisites
- Make clearer how to enable Auto DevOps from settings
- Add WIP base domain section

2 files changed, 117 insertions, 71 deletions

diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md
index c9d32cacb55..1dc964591c0 100644
--- a/doc/topics/autodevops/index.md
+++ b/doc/topics/autodevops/index.md
@@ -1,18 +1,15 @@
 # Auto DevOps
 
-> [Introduced][ce-37115] in GitLab 10.0, Auto DevOps is currently in **Beta**.
+DANGER: Auto DevOps is currently in **Beta** and _not recommended for production use_.
 
-With Auto DevOps, the software development process becomes easier to set up
-as every project can have a complete workflow from build to deploy, with minimal
-to zero configuration. Comprised by a set of stages, Auto DevOps brings the best
-practices to your project in an easy and default way.
-
-## Overview
+> [Introduced][ce-37115] in GitLab 10.0.
 
-The power of Auto DevOps lies in the fact that it can set up your project's
-CI/CD without the need to provide your own `.gitlab-ci.yml`.
+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.
 
-The stages of Auto DevOps include:
+Comprised of a set of stages, Auto DevOps brings the best practices to your
+project in an easy and default way:
 
 1. [Auto Build](#auto-build)
 1. [Auto Test](#auto-test)
@@ -22,32 +19,36 @@ The stages of Auto DevOps include:
 1. [Auto Monitoring](#-auto-monitoring)
 
 At the beginning of the Auto DevOps setup, you are provided with some defaults
-for all the stages. You can however [customize](#customizing) almost everything
+for all the stages, you can, however, [customize](#customizing) almost everything
 to your needs.
 
-## Quick start
-
-If you are using GitLab.com, see our [quick start guide](quick_start_guide.md)
-for using Auto DevOps with GitLab.com and an external Kubernetes cluster on
-Google Cloud.
-
-For self-hosted installations, the easiest way to make use of Auto DevOps is to
-install GitLab inside a Kubernetes cluster using the [Omnibus GitLab Helm
-Chart](../../install/kubernetes/gitlab_omnibus.md) which automatically installs
-and configures everything you need.
-
 ## Prerequisites
 
-You will need one or more GitLab Runners, a Kubernetes cluster, and Prometheus
+You will need a Kubernetes cluster, one or more GitLab Runners, and Prometheus
 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.
 
-If you are using GitLab outside of Kubernetes, for example with GitLab.com, then
-you should take these prerequisites into account:
+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.
 
-1. **Base domain** - You will need a base domain configured with wildcard DNS to
-   be used by all of your Auto DevOps applications.
+| **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 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. |
+| [Auto Deploy](#auto-deploy)             | 1) Kubernetes cluster, 2) GitLab Runner with Kubernetes or Docker executor, 3) base domain set up, 4) Kubernetes integration enabled. |
+| [Auto Monitoring](#-auto-monitoring)    | 1) Kubernetes cluster, 2) Prometheus, 3) Prometheus and Kubernetes integrations enabled. |
+
+TIP: **Tip:**
+The whole setup is a lot easier if you install GitLab in Kubernetes using the
+[Omnibus GitLab Helm Chart](../../install/kubernetes/gitlab_omnibus.md) since
+almost all of the above requirements are taken care automatically.
+
+If GitLab is installed outside of Kubernetes, for example when using Auto DevOps
+with GitLab.com, then you should take these prerequisites into account:
 
 1. **GitLab Runner** - Your Runner needs to be configured to be able to run Docker.
    Generally this means using the
@@ -61,7 +62,8 @@ you should take these prerequisites into account:
    should be registered as [shared Runners](../../ci/runners/README.md#registering-a-shared-runner)
    for the entire GitLab instance, or [specific Runners](../../ci/runners/README.md#registering-a-specific-runner)
    that are assigned to specific projects.
-
+1. **Base domain** - You will need a base domain configured with wildcard DNS to
+   be used by all of your Auto DevOps applications.
 1. **Kubernetes** - To enable deployments, you will need Kubernetes 1.5+, with NGINX
    ingress and wildcard SSL termination, for example using the
    [`nginx-ingress`](https://github.com/kubernetes/charts/tree/master/stable/nginx-ingress)
@@ -70,7 +72,6 @@ you should take these prerequisites into account:
    integration will need to be enabled for the project, or enabled as a
    [default service template](../../user/project/integrations/services_templates.md)
    for the entire GitLab installation.
-
 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),
@@ -80,6 +81,17 @@ you should take these prerequisites into account:
    [default service template](../../user/project/integrations/services_templates.md)
    for the entire GitLab installation.
 
+## Quick start
+
+If you are using GitLab.com, see our [quick start guide](quick_start_guide.md)
+for using Auto DevOps with GitLab.com and an external Kubernetes cluster on
+Google Cloud.
+
+For self-hosted installations, the easiest way to make use of Auto DevOps is to
+install GitLab inside a Kubernetes cluster using the [Omnibus GitLab Helm
+Chart](../../install/kubernetes/gitlab_omnibus.md) which automatically installs
+and configures everything you need.
+
 ## Enabling Auto DevOps
 
 NOTE: **Note:**
@@ -89,15 +101,18 @@ full use of Auto DevOps. If this is your fist time, we recommend you follow the
 
 ### New projects
 
-To enable Auto DevOps for new projects in GitLab:
+NOTE: **Note:**
+If the Auto DevOps setting has been enabled by your GitLab admin, then it should
+be enabled for newly created projects. If not, you'll need to explicitly
+enable it.
 
-1. Go to your project's **Settings > CI/CD > General pipelines settings** and
-   find the Auto DevOps section. On new projects where no `.gitlab-ci.yml` is
-   detected, a banner with info how to enable Auto DevOps will appear. Clicking
+To enable Auto DevOps for new projects with no `.gitlab-ci.yml` present:
+
+1. A banner with info how to enable Auto DevOps will appear. Clicking
    on that link will take you straight to the relevant CI/CD settings page.
 1. Select "Enable Auto DevOps".
-1. Add in your base domain that will be used by Kubernetes to deploy your
-   application.
+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.
 
 Finally, a pipeline needs to be triggered. Since new projects don't have a
@@ -107,21 +122,42 @@ and create one for the `master` branch.
 
 ### Existing projects
 
-To enable Auto DevOps for existing projects in GitLab:
+To enable Auto DevOps for existing projects with a `.gitlab-ci.yml` present:
 
 1. Go to your project's **Settings > CI/CD > General pipelines settings** and
    find the Auto DevOps section.
 1. Select "Enable Auto DevOps".
-1. Add in your base domain that will be used by Kubernetes to deploy your
-   application.
+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 all you need to do is either remove your existing `.gitlab-ci.yml` or
 [customize it](#customizing-gitlab-ci-yml) to your liking.
 
+## Auto DevOps base domain
+
+TODO
+
+The Auto DevOps base domain is required if you want to make use of Auto
+Review Apps and Auto Deploy.
+
+The IP being the IP of your load balancer, nginx generally.
+
+You need a wildcard DNS for that domain. i.e. set up an A record for
+`*.<base domain>` that points to the IP address of your NGINX ingress
+load balancer or the IP address you provided during installation, if installed
+GitLab using `gitlab-omnibus` chart.
+All requests hit nginx, and then nginx routes those requests to the k8s pods
+
+For GitLab installed inside k8s, there are two options, provide a static IP, or have one assigned.
+
+So in the quick start guide, it’s using the assigned IP address of the nginx controller
+which you just installed in the previous step of set up ingress controller
+
 ## Stages of Auto DevOps
 
-The following sections describe the stages of Auto DevOps.
+The following sections describe the stages of Auto DevOps. Read them carefully
+to understand how each one works.
 
 ### Auto Build
 
@@ -137,14 +173,15 @@ Either way, the resulting Docker image is automatically pushed to the
 
 ### Auto Test
 
-Auto Test automatically tests your application using
+Auto Test automatically run the appropriate tests for your application using
 [Herokuish](https://github.com/gliderlabs/herokuish) and [Heroku
-buildpacks](https://devcenter.heroku.com/articles/buildpacks). Auto Test will
-analyze your project to detect the language and framework, and run appropriate
-tests. Several languages and frameworks are detected automatically, but if your
-language is not detected, you may succeed with a [custom
-buildpack](#custom-buildpack).
+buildpacks](https://devcenter.heroku.com/articles/buildpacks) by analyzing
+your project to detect the language and framework. Several languages and
+frameworks are detected automatically, but if your language is not detected,
+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 in your application. If there are no
 tests, it's up to you to add them.
 
@@ -154,20 +191,23 @@ 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, creating a report
 that is uploaded as an artifact. In GitLab EE, differences between the source
-and target branches are shown in the merge request widget. *GitLab is in no way
-affiliated with Code Climate.*
+and target branches are
+[shown in the merge request widget](https://docs.gitlab.com/ee/user/project/merge_requests/code_quality_diff.html).
+
+_GitLab is in no way affiliated with Code Climate while we thank them for their
+awesome tools._
 
 ### Auto Review Apps
 
->**Note:**
+CAUTION: **Caution:**
 Your apps should be manipulated only using Helm and not directly from Kubernetes.
 
-Auto Review Apps create a [Review App][review-app] for each branch. Review Apps
-are temporary application environments based on the branch's code so developers,
-designers, QA, product managers, and other reviewers can actually see and
-interact with code changes as part of the review process.
+[Review Apps][review-app] are temporary application environments based on the
+branch's code so developers, designers, QA, product managers, and other
+reviewers can actually see and interact with code changes as part of the review
+process. Auto Review Apps create a Review App for each branch.
 
-The review app will have a unique URL based on the project name, the branch
+The Review App will have a unique URL based on the project name, the branch
 name, and a unique number, combined with the Auto DevOps base domain. For
 example, `user-project-branch-1234.example.com`. A link to the Review App shows
 up in the merge request widget for easy discovery. When the branch is deleted,
@@ -181,7 +221,7 @@ DevOps setting), the job will silently be skipped.
 
 ### Auto Deploy
 
->**Note:**
+CAUTION: **Caution:**
 Your apps should be manipulated only using Helm and not directly from Kubernetes.
 
 After a branch or merge request is merged into `master`, Auto Deploy deploys the
@@ -193,7 +233,7 @@ available. If the Kubernetes service is not configured, or if the variable
 DevOps setting), the job will silently be skipped.
 
 Auto Deploy doesn't include deployments to staging or canary by default, but the
-Auto DevOps template contains job definitions for these tasks if you want to
+[Auto DevOps template] contains job definitions for these tasks if you want to
 enable them.
 
 ### Auto Monitoring
@@ -241,12 +281,11 @@ or a `.buildpack` file in your project:
 
 - **Project variable** - Create a project variable `BUILDPACK_URL` with the URL
   of the buildpack to use.
-
 - **`.buildpack` file** - Add a file in your project's repo called  `.buildpack`
   and add the URL of the buildpack to use on a line in the file. If you want to
-  use multiple buildpacks, you can enter them in, one on each line
+  use multiple buildpacks, you can enter them in, one on each line.
 
-    >**Note:** Using multiple buildpacks may break Auto Test.
+CAUTION: **Caution:** Using multiple buildpacks may break Auto Test.
 
 ### Custom `Dockerfile`
 
@@ -257,13 +296,13 @@ Dockerfile is based on [Alpine](https://hub.docker.com/_/alpine/).
 
 ### Custom Helm Chart
 
-Auto DevOps uses Helm to deploy your application to Kubernetes. You can override
-the Helm chart used by bundling up a chart into your project repo or by
+Auto DevOps uses [Helm](https://helm.sh/) to deploy your application to Kubernetes.
+You can override the Helm chart used by bundling up a chart into your project repo or by
 specifying a project variable.
 
-**Bundled chart** - If your project has a `chart` directory with a `Chart.yaml`
+**Bundled chart** - If your project has a `./charts` directory with a `Chart.yaml`
 file in it, Auto DevOps will detect the chart and use it instead of the default
-chart. This can be a great way to control exactly how your application is
+one. This can be a great way to control exactly how your application is
 deployed.
 
 **Project variable** - Create a project variable `AUTO_DEVOPS_CHART` with the
@@ -322,6 +361,7 @@ TIP: **Tip:** Regarding the replica variables (`*_REPLICAS`), technically, you
 could name your track `beta` or `whatever`. The Auto DevOps template defaults
 to `canary` and empty for canary and stable deployments respectively.
 
+
 ## Currently supported languages
 
 >**Note:**
@@ -386,16 +426,20 @@ planned for a subsequent release.
 If an administrator would like to disable the banners on an instance level, this
 feature can be disabled either through the console:
 
-```basb
-$ gitlab-rails console
-[1] pry(main)> Feature.get(:auto_devops_banner_disabled).disable
-=> true
+```sh
+sudo gitlab-rails console
 ```
 
-Or through the HTTP API with the admin access token:
+Then run:
 
+```ruby
+Feature.get(:auto_devops_banner_disabled).disable
 ```
-curl --data "value=true" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/features/auto_devops_banner_disabled
+
+Or through the HTTP API with an admin access token:
+
+```sh
+curl --data "value=true" --header "PRIVATE-TOKEN: private_token" https://gitlab.example.com/api/v4/features/auto_devops_banner_disabled
 ```
 
 [ce-37115]: https://gitlab.com/gitlab-org/gitlab-ce/issues/37115
diff --git a/doc/topics/autodevops/quick_start_guide.md b/doc/topics/autodevops/quick_start_guide.md
index c51a8cbef98..78f1f8dcbd4 100644
--- a/doc/topics/autodevops/quick_start_guide.md
+++ b/doc/topics/autodevops/quick_start_guide.md
@@ -1,13 +1,15 @@
 # Auto DevOps: quick start guide
 
-> [Introduced][ce-37115] in GitLab 10.0, Auto DevOps is currently in **Beta**.
+DANGER: Auto DevOps is currently in **Beta** and _not recommended for production use_.
+
+> [Introduced][ce-37115] in GitLab 10.0.
 
 This is a step-by-step guide to deploying a project hosted on GitLab.com to
 Google Cloud, using Auto DevOps.
 
 We made a minimal [Ruby
-application](https://gitlab.com/gitlab-examples/minimal-ruby-app) to use as an
-example for this guide. It contains two files:
+application](https://gitlab.com/auto-devops-examples/minimal-ruby-app) to use
+as an example for this guide. It contains two main files:
 
 * `server.rb` - our application. It will start an HTTP server on port 5000 and
   render "Hello, world!"