Get rid most of the irrelevant sections

[ci skip]

2 files changed, 27 insertions, 32 deletions

diff --git a/doc/ci/review_apps/img/review_apps_preview_in_mr.png b/doc/ci/review_apps/img/review_apps_preview_in_mr.png
new file mode 100644
index 00000000000..15bcb90518c
--- /dev/null
+++ b/doc/ci/review_apps/img/review_apps_preview_in_mr.png
diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md
index ce1fbaaab04..b4abb8c0e5c 100644
--- a/doc/ci/review_apps/index.md
+++ b/doc/ci/review_apps/index.md
@@ -19,8 +19,19 @@ any way you'd like.
 
 ## Overview
 
-Simply put, a Review App is a mapping of
-a branch with an environment as there is a 1:1 relation between them.
+Simply put, a Review App is a mapping of a branch with an environment as there
+is a 1:1 relation between them.
+
+Here's an example of what it looks like when viewing a merge request with a
+dynamically set environment.
+
+![Review App in merge request](img/review_apps_preview_in_mr.png)
+
+In the image above you can see that the `add-new-line` branch was successfully
+built and deployed under a dynamic environment and can be previewed with an
+also dynamically URL.
+
+---
 
 To get a better understanding of Review Apps, you must first learn how
 environments and deployments work. The following docs will help you grasp that
@@ -34,9 +45,9 @@ knowledge:
    how environments work.
 1. Additionally, find out about [manual actions][] and how you can use them to
    deploy to critical environments like production with the push of a button.
-1. And as a last step, follow the [NGINX example tutorial][app-nginx] which will
+1. And as a last step, follow the [example tutorials](#examples) which will
    guide you step by step to set up the infrastructure and make use of
-   Review Apps with a simple HTML site and NGINX.
+   Review Apps.
 
 ## Configuration
 
@@ -66,7 +77,18 @@ From there on, you would follow the branched Git flow:
 1. Click on the link that's present in the MR related to the branch and see the
    changes live.
 
-### Limitations
+## Distinguish between production and review apps
+
+1. We need some form to distinguish between production/staging and review app environment,
+
+- Are dynamic environments distinguishable by the slash in `environment:url`?
+
+We would expect the environments to be of `type/name`:
+
+1. This would allow us to have a clear distinction between different environment types: `production/gitlab.com`, `staging/dev`, `review-apps/feature/branch`,
+3. We would be aware of some of these types and for example for `review-apps` show them differently in context of Merge Requests, ex. calculating `deployed ago` a little differently.
+
+## Limitations
 
 We are limited to use only [CI predefined variables][variables].
 
@@ -83,33 +105,6 @@ And below is a soon to be added examples list:
 - Use on Heroku with dpl
 - Use with OpenShift/kubernetes
 
-## Assumptions
-
-1. We will allow to create dynamic environments from `.gitlab-ci.yml`, by allowing to specify environment variables: `review_apps_${CI_BUILD_REF_NAME}`,
-1. We will use multiple deployments of the same application per environment,
-1. The URL will be assigned to environment on the creation, and updated later if necessary,
-1. The URL will be specified in `.gitlab-ci.yml`, possibly introducing regexp for getting an URL from build log if required,
-1. We need some form to distinguish between production/staging and review app environment,
-1. We don't try to manage life cycle of deployments in the first iteration, possibly we will extend a Pipeline to add jobs that will be responsible either for cleaning up or removing old deployments and closing environments.
-
-## Distinguish between production and review apps
-
-- Are dynamic environments distinguishable by the slash in `environment:url`?
-
-### Convention over configuration
-
-We would expect the environments to be of `type/name`:
-
-1. This would allow us to have a clear distinction between different environment types: `production/gitlab.com`, `staging/dev`, `review-apps/feature/branch`,
-2. Since we use a folder structure we could group all environments by `type` and strip that from environment name,
-3. We would be aware of some of these types and for example for `review-apps` show them differently in context of Merge Requests, ex. calculating `deployed ago` a little differently.
-3. We could easily group all `types` across from group from all projects.
-
-The `type/name` also plays nice with `Variables` and `Runners`, because we can limit their usage:
-
-1. We could extend the resources with a field that would allow us to filter for what types it can be used, ex.: `production/*` or `review-apps/*`
-2. We could limit runners to be used only by `review-apps/*`,
-
 [app-nginx]: nginx_guide.md
 [ce-21971]: https://gitlab.com/gitlab-org/gitlab-ce/issues/21971
 [dynamic environments]: ../environments.md#dynamic-environments