Begin writing Overview section

2 files changed, 30 insertions, 89 deletions

diff --git a/doc/ci/environments.md b/doc/ci/environments.md
index 9d65621fbbb..60541c44016 100644
--- a/doc/ci/environments.md
+++ b/doc/ci/environments.md
@@ -3,20 +3,38 @@
 >**Note:**
 Introduced in GitLab 8.9.
 
-During the development of a software there can be many stages until it's ready
-for public consumption. You sure want to first see your code in a testing or
-staging environment before you release it to the public. That way you can
-prevent bugs not only in your software, but in the deployment process as well.
-
-With environments you can control the Continuous Deployment of your software all
+During the development of a software, there can be many stages until it's ready
+for public consumption. You sure want to first test your code and then deploy it
+in a testing or staging environment before you release it to the public. That
+way you can prevent bugs not only in your software, but in the deployment
+process as well.
+
+In case you use GitLab CI to not only test or build your project, but also
+deploy it in your infrastructure, GitLab provides a way to track your deployments
+so you always know what is currently being deployed on your servers. With
+environments you can control the Continuous Deployment of your software all
 within GitLab. All you need to do is define them in your project's
-[`.gitlab-ci.yml`][yaml].
+[`.gitlab-ci.yml`][yaml]. GitLab provides a full history of your deployments per
+every environment.
+
+## Overview
+
+Deployments are created when [jobs] deploy versions of code to environments,
+so every environment can have one or more deployments. GitLab keeps track of
+your deployments, so you always know what is currently being deployed on your
+servers.
+
+Environments are like tags for your CI jobs, describing where code gets deployed.
+CI/CD [Pipelines] usually have one or more [jobs] that deploy to an environment.
+You can think of names such as testing, staging or production.
 
-In the following sections, we'll see how that works.
+Defining environments in a project's `.gitlab-ci.yml` lets developers track
+[deployments] to these environments.
 
-## An environments example
+The environments page can only be viewed by Reporters and above. For more
+information on the permissions, see the [permissions documentation][permissions].
 
-Let's assume that you have 
+Let's assume that you have:
 
 1. Define the environments in `.gitlab-ci.yml`
 1. Push the repository to GitLab
@@ -41,18 +59,6 @@ View commit SHA that triggered the deployment
 View branch the deployment was based on
 View time ago the deployment was performed
 
-Environments are like tags for your CI jobs, describing where code gets deployed.
-
-You can think of names such as testing, staging or production.
-
-CI/CD [Pipelines] usually have one or more [jobs] that deploy to an environment.
-
-Defining environments in a project's `.gitlab-ci.yml` lets developers track
-[deployments] to these environments.
-
-The environments page can only be viewed by Reporters and above. For more
-information on the permissions, see the [permissions documentation][permissions].
-
 ### Defining environments
 
 While you can create and delete environments manually in the web interface, we
@@ -129,13 +135,6 @@ stop_review:
     action: stop
 ```
 
-## The relationship between deployments and environments
-
-Deployments are created when [jobs] deploy versions of code to [environments],
-so every environment can have one or more deployments. GitLab keeps track of
-your deployments, so you always know what is currently being deployed on your
-servers.
-
 ### View the deployment history
 
 Clicking on an environment will show the history of deployments.
diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index 5c7d300e3d9..5c0e1c44e3f 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -573,8 +573,7 @@ In its simplest form, the `environment` keyword can be defined like:
 deploy to production:
   stage: deploy
   script: git push production HEAD:master
-  environment:
-    name: production
+  environment: production
 ```
 
 In the above example, the `deploy to production` job will be marked as doing a
@@ -674,61 +673,6 @@ The `stop_review_app` job is **required** to have the following keywords defined
 - `environment:name`
 - `environment:action`
 
-#### environment:name
-
-#### environment:url
-
-Optional.
-
-#### environment:on_stop
-
-> [Introduced][ce-6669] in GitLab 8.13.
-
-Closing environments can be achieved with the `on_stop` keyword defined under
-`environment`. It declares a different job that has to be run in order to close
-the environment.
-
-This job is required to have the following keywords defined:
-
-- `when` - [reference](#when)
-- `environment:name`
-- `environment:action` - reference below
-
-See below for an example.
-
-#### environment:action
-
-> [Introduced][ce-6669] in GitLab 8.13.
-
-The `action` keyword is to be used in conjunction with `on_stop` and is defined
-in the job that depends on the one that was called from.
-
-Take for instance:
-
-```yaml
-review:
-  stage: deploy
-  script: make deploy-app
-  environment:
-    name: review
-    on_stop: stop_review
-
-stop_review:
-  stage: deploy
-  script: make delete-app
-  when: manual
-  environment:
-    name: review
-    action: stop
-```
-
-In the above example we set up the `review` job to deploy to the `review`
-environment, and we also defined a new `stop_review` job under `on_stop`.
-Once the `review` job is successfully finished, it will trigger the `stop_review`
-job based on what is defined under `when`. In this case we set it up to `manual`
-so it will need a [manual action](#manual-actions) via GitLab's web interface
-in order to run.
-
 #### dynamic environments
 
 > [Introduced][ce-6323] in GitLab 8.12 and GitLab Runner 1.6.
@@ -737,9 +681,7 @@ in order to run.
 These parameters can use any of the defined [CI variables](#variables)
 (including predefined, secure variables and `.gitlab-ci.yml` variables).
 
----
-
-**Example configurations**
+For example:
 
 ```
 deploy as review app: