Refactor review apps doco and CI landing pagedocs/restructure-review-apps-docs

2 files changed, 62 insertions, 99 deletions

diff --git a/doc/ci/README.md b/doc/ci/README.md
index a7ad2018b09..123a5e50f14 100644
--- a/doc/ci/README.md
+++ b/doc/ci/README.md
@@ -38,30 +38,27 @@ implementing CI/CD. Auto DevOps:
 
 For complete control, you can manually configure GitLab CI/CD.
 
-### Usage
+### Configuration and Usage
 
-With basic knowledge of how GitLab CI/CD works, the following documentation extends your knowledge
-into more features:
+The following topics contain configuration and usage information for all features of GitLab CI/CD:
 
 | Topic                                                                                                                     | Description                                                                                |
 |:--------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------|
 | [Creating and using CI/CD pipelines](pipelines.md)                                                                        | Understand, visualize, create, and use CI/CD pipelines.                                    |
-| [CI/CD Variables](variables/README.md)                                                                                    | How environment variables can be configured and made available in pipelines.               |
-| [Where variables can be used](variables/where_variables_can_be_used.md)                                                   | A deeper look into where and how CI/CD variables can be used.                              |
-| [User](../user/permissions.md#gitlab-cicd-permissions) and [job](../user/permissions.md#job-permissions) permissions      | Learn about the access levels a user can have for performing certain CI actions.           |
-| [Configuring GitLab Runners](runners/README.md)                                                                           | Documentation for configuring [GitLab Runner](https://docs.gitlab.com/runner/).            |
+| [CI/CD Variables](variables/README.md)                                                                                    | Configuring and using environment variables in pipelines.                                  |
+| [Where variables can be used](variables/where_variables_can_be_used.md)                                                   | Where and how CI/CD variables can be used.                                                 |
+| [User](../user/permissions.md#gitlab-cicd-permissions) and [job](../user/permissions.md#job-permissions) permissions      | User access levels for performing certain CI actions.                                      |
+| [Configuring GitLab Runners](runners/README.md)                                                                           | Configuring [GitLab Runner](https://docs.gitlab.com/runner/).                              |
 | [Environments and deployments](environments.md)                                                                           | Deploy the output of jobs into environments for reviewing, staging, and production.        |
-| [Job artifacts](../user/project/pipelines/job_artifacts.md)                                                               | Learn about the output of jobs.                                                            |
-| [Cache dependencies in GitLab CI/CD](caching/index.md)                                                                    | Discover how to speed up pipelines using caching.                                          |
+| [Review Apps](review_apps/index.md)                                                                                       | Configure GitLab CI/CD to preview code changes.                                            |
+| [Job artifacts](../user/project/pipelines/job_artifacts.md)                                                               | Using the output of jobs.                                                                  |
+| [Cache dependencies in GitLab CI/CD](caching/index.md)                                                                    | Speed up pipelines using caching.                                                          |
 | [Using Git submodules with GitLab CI](git_submodules.md)                                                                  | How to run your CI jobs when using Git submodules.                                         |
-| [Pipelines for merge requests](merge_request_pipelines/index.md)                                                          | Create pipelines specifically for merge requests.                                          |
 | [Using SSH keys with GitLab CI/CD](ssh_keys/README.md)                                                                    | Use SSH keys in your build environment.                                                    |
 | [Triggering pipelines through the API](triggers/README.md)                                                                | Use the GitLab API to trigger a pipeline.                                                  |
-| [Pipeline schedules](../user/project/pipelines/schedules.md)                                                              | Trigger pipelines on a schedule.                                                           |
 | [Connecting GitLab with a Kubernetes cluster](../user/project/clusters/index.md)                                          | Integrate one or more Kubernetes clusters to your project.                                 |
 | [ChatOps](chatops/README.md)                                                                                              | Trigger CI jobs from chat, with results sent back to the channel.                          |
 | [Interactive web terminals](interactive_web_terminal/index.md)                                                            | Open an interactive web terminal to debug the running jobs.                                |
-| [Review Apps](review_apps/index.md)                                                                                       | Configure GitLab CI/CD to preview code changes in a per-branch basis.                      |
 | [Optimizing GitLab for large repositories](large_repositories/index.md)                                                   | Useful tips on how to optimize GitLab and GitLab Runner for big repositories.              |
 | [Deploy Boards](https://docs.gitlab.com/ee/user/project/deploy_boards.html) **[PREMIUM]**                                 | Check the current health and status of each CI/CD environment running on Kubernetes.       |
 | [GitLab CI/CD for external repositories](https://docs.gitlab.com/ee/ci/ci_cd_for_external_repos/index.html) **[PREMIUM]** | Get the benefits of GitLab CI/CD combined with repositories in GitHub and BitBucket Cloud. |
diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md
index 2fc1e14f02e..1a71c5fd258 100644
--- a/doc/ci/review_apps/index.md
+++ b/doc/ci/review_apps/index.md
@@ -3,12 +3,10 @@
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/21971) in GitLab 8.12. Further additions were made in GitLab 8.13 and 8.14.
 > - Inspired by [Heroku's Review Apps](https://devcenter.heroku.com/articles/github-integration-review-apps), which itself was inspired by [Fourchette](https://github.com/rainforestapp/fourchette).
 
-For a video introduction to Review Apps, see [8.14 Webcast: Review Apps & Time Tracking Beta (EE) - GitLab Release](https://www.youtube.com/watch?v=CteZol_7pxo).
-
-## Overview
-
 Review Apps are a collaboration tool that takes the hard work out of providing an environment to showcase product changes.
 
+## Introduction
+
 Review Apps:
 
 - Provide an automatic live preview of changes made in a feature branch by spinning up a dynamic environment for your merge requests.
@@ -18,103 +16,60 @@ Review Apps:
 
 ![Review Apps Workflow](img/continuous-delivery-review-apps.svg)
 
-Reviewing anything, from performance to interface changes, becomes much easier with a live environment and so Review Apps can make a large impact on your development flow.
+In the above example:
 
-## What are Review Apps?
+- A Review App is built every time a commit is pushed to`topic branch`.
+- The reviewer fails two reviews before passing the third review.
+- Once the review as passed, `topic branch` is merged into `master` where it's deploy to staging.
+- After been approved in staging, the changes that were merged into `master` are deployed in to production.
 
-A Review App is a mapping of a branch with an [environment](../environments.md). The following is an example of a merge request with an environment set dynamically.
+### How Review Apps work
+
+A Review App is a mapping of a branch with an [environment](../environments.md).
+Access to the Review App is made available as a link on the [merge request](../../user/project/merge_requests.md) relevant to the branch.
+
+The following is an example of a merge request with an environment set dynamically.
 
 ![Review App in merge request](img/review_apps_preview_in_mr.png)
 
-In this example, you can see a branch was:
+In this example, a branch was:
 
 - Successfully built.
 - Deployed under a dynamic environment that can be reached by clicking on the **View app** button.
 
-## How do Review Apps work?
-
-The basis of Review Apps in GitLab is [dynamic environments](../environments.md#configuring-dynamic-environments), which allow you to dynamically create a new environment for each branch.
-
-Access to the Review App is made available as a link on the [merge request](../../user/project/merge_requests.md) relevant to the branch. Review Apps enable you to review all changes proposed by the merge request in live environment.
-
-## Use cases
-
-Some supported use cases include the:
-
-- Simple case of deploying a simple static HTML website.
-- More complicated case of an application that uses a database. Deploying a branch on a temporary instance and booting up this instance with all required software and services automatically on the fly is not a trivial task. However, it is possible, especially if you use Docker or a configuration management tool like Chef, Puppet, Ansible, or Salt.
-
-Review Apps usually make sense with web applications, but you can use them any way you'd like.
-
-## Implementing Review Apps
-
-Implementing Review Apps depends on your:
-
-- Technology stack.
-- Deployment process.
-
-### Prerequisite Knowledge
-
-To get a better understanding of Review Apps, review documentation on how environments and deployments work. Before you implement your own Review Apps:
-
-1. Learn about [environments](../environments.md) and their role in the development workflow.
-1. Learn about [CI variables](../variables/README.md) and how they can be used in your CI jobs.
-1. Explore the [`environment` syntax](../yaml/README.md#environment) as defined in `.gitlab-ci.yml`. This will become a primary reference.
-1. Additionally, find out about [manual actions](../environments.md#configuring-manual-deployments) and how you can use them to deploy to critical environments like production with the push of a button.
-1. Follow the [example tutorials](#examples). These will guide you through setting up infrastructure and using Review Apps.
-
-### Configuring dynamic environments
-
-Configuring Review Apps dynamic environments depends on your technology stack and infrastructure.
-
-For more information, see [dynamic environments](../environments.md#configuring-dynamic-environments) documentation to understand how to define and create them.
-
-### Creating and destroying Review Apps
-
-Creating and destroying Review Apps is defined in `.gitlab-ci.yml` at a job level under the `environment` keyword.
+## Configuring Review Apps
 
-For more information, see [Introduction to environments and deployments](../environments.md).
+Review Apps are built on [dynamic environments](../environments.md#configuring-dynamic-environments), which allow you to dynamically create a new environment for each branch.
 
-### Adding Review Apps to your workflow
-
-The process of adding Review Apps in your workflow is as follows:
+The process of configuring Review Apps is as follows:
 
 1. Set up the infrastructure to host and deploy the Review Apps.
 1. [Install](https://docs.gitlab.com/runner/install/) and [configure](https://docs.gitlab.com/runner/commands/) a Runner to do deployment.
 1. Set up a job in `.gitlab-ci.yml` that uses the [predefined CI environment variable](../variables/README.md) `${CI_COMMIT_REF_NAME}` to create dynamic environments and restrict it to run only on branches.
 1. Optionally, set a job that [manually stops](../environments.md#stopping-an-environment) the Review Apps.
 
-After adding Review Apps to your workflow, you follow the branched Git flow. That is:
+### Examples
 
-1. Push a branch and let the Runner deploy the Review App based on the `script` definition of the dynamic environment job.
-1. Wait for the Runner to build and deploy your web application.
-1. Click on the link that provided in the merge request related to the branch to see the changes live.
-
-## Limitations
-
-Check the [environments limitations](../environments.md#limitations).
-
-## Examples
-
-The following are example projects that use Review Apps with:
+The following are example projects that demonstrate Review App configuration:
 
 - [NGINX](https://gitlab.com/gitlab-examples/review-apps-nginx).
 - [OpenShift](https://gitlab.com/gitlab-examples/review-apps-openshift).
 
 See also the video [Demo: Cloud Native Development with GitLab](https://www.youtube.com/watch?v=jfIyQEwrocw), which includes a Review Apps example.
 
-## Route Maps
+### Route Maps
 
-> Introduced in GitLab 8.17. In GitLab 11.5 the file links
-are surfaced to the merge request widget.
+> Introduced in GitLab 8.17. In GitLab 11.5, the file links are available in the merge request widget.
 
 Route Maps allows you to go directly from source files
 to public pages on the [environment](../environments.md) defined for
-Review Apps. Once set up, the review app link in the merge request
+Review Apps.
+
+Once set up, the review app link in the merge request
 widget can take you directly to the pages changed, making it easier
 and faster to preview proposed modifications.
 
-All you need to do is to tell GitLab how the paths of files
+Configuring Route Maps involves telling GitLab how the paths of files
 in your repository map to paths of pages on your website using a Route Map.
 Once set, GitLab will display **View on ...** buttons, which will take you
 to the pages changed directly from merge requests.
@@ -123,9 +78,9 @@ To set up a route map, add a a file inside the repository at `.gitlab/route-map.
 which contains a YAML array that maps `source` paths (in the repository) to `public`
 paths (on the website).
 
-### Route Maps example
+#### Route Maps example
 
-Below there's an example of a route map for [Middleman](https://middlemanapp.com),
+The following is an example of a route map for [Middleman](https://middlemanapp.com),
 a static site generator (SSG) used to build [GitLab's website](https://about.gitlab.com),
 deployed from its [project on GitLab.com](https://gitlab.com/gitlab-com/www-gitlab-com):
 
@@ -147,18 +102,17 @@ deployed from its [project on GitLab.com](https://gitlab.com/gitlab-com/www-gitl
   public: '\1' # images/blogimages/around-the-world-in-6-releases-cover.png
 ```
 
-Mappings are defined as entries in the root YAML array, and are identified by a `-` prefix. Within an entry, we have a hash map with two keys:
+Mappings are defined as entries in the root YAML array, and are identified by a `-` prefix. Within an entry, there is a hash map with two keys:
 
 - `source`
-    - a string, starting and ending with `'`, for an exact match
-    - a regular expression, starting and ending with `/`, for a pattern match
-      - The regular expression needs to match the entire source path - `^` and `$` anchors are implied.
-      - Can include capture groups denoted by `()` that can be referred to in the `public` path.
-      - Slashes (`/`) can, but don't have to, be escaped as `\/`.
-      - Literal periods (`.`) should be escaped as `\.`.
-- `public`
-    - a string, starting and ending with `'`.
-      - Can include `\N` expressions to refer to capture groups in the `source` regular expression in order of their occurrence, starting with `\1`.
+  - A string, starting and ending with `'`, for an exact match.
+  - A regular expression, starting and ending with `/`, for a pattern match:
+    - The regular expression needs to match the entire source path - `^` and `$` anchors are implied.
+    - Can include capture groups denoted by `()` that can be referred to in the `public` path.
+    - Slashes (`/`) can, but don't have to, be escaped as `\/`.
+    - Literal periods (`.`) should be escaped as `\.`.
+- `public`, a string starting and ending with `'`.
+  - Can include `\N` expressions to refer to capture groups in the `source` regular expression in order of their occurrence, starting with `\1`.
 
 The public path for a source path is determined by finding the first
 `source` expression that matches it, and returning the corresponding
@@ -171,12 +125,12 @@ will match `/source\/(.+?\.html).*/` instead of `/source\/(.*)/`,
 and will result in a public path of `index.html`, instead of
 `index.html.haml`.
 
-Once you have the route mapping set up, it will be exposed in a few places:
+Once you have the route mapping set up, it will take effect in the following locations:
 
-- In the merge request widget. The **View app** button will take you to the
-  environment URL you have set up in `.gitlab-ci.yml`. The dropdown will render
-  the first 5 matched items from the route map, but you can filter them if more
-  than 5 are available.
+- In the merge request widget. The:
+  - **View app** button will take you to the environment URL set in `.gitlab-ci.yml`.
+  - Dropdown will list the first 5 matched items from the route map, but you can filter them if more
+    than 5 are available.
 
     ![View app file list in merge request widget](img/view_on_mr_widget.png)
 
@@ -187,3 +141,15 @@ Once you have the route mapping set up, it will be exposed in a few places:
 - In the blob file view.
 
     !["View on env" button in file view](img/view_on_env_blob.png)
+
+## Working with Review Apps
+
+After adding Review Apps to your workflow, you follow the branched Git flow. That is:
+
+1. Push a branch and let the Runner deploy the Review App based on the `script` definition of the dynamic environment job.
+1. Wait for the Runner to build and deploy your web application.
+1. Click on the link that provided in the merge request related to the branch to see the changes live.
+
+## Limitations
+
+Review App limitations are the same as [environments limitations](../environments.md#limitations).