Better docs structure and fixed most of grammar

3 files changed, 60 insertions, 65 deletions

diff --git a/doc/deployment/README.md b/doc/deployment/README.md
index 137a519..199ad9d 100644
--- a/doc/deployment/README.md
+++ b/doc/deployment/README.md
@@ -1,37 +1,26 @@
-## GitLab-CI deployment
+## Using Dpl as deployment tool
+Dpl (dee-pee-ell) is a deploy tool made for continuous deployment that's developed and used by Travis CI, but can also be used with GitLab CI. 
 
-GitLab-CI support deployment builds. Deploy Builds that are ran when all other builds have succeeded. This builds can be defined using simple syntax:
-
-```yaml
-production:
-  type: deploy
-  script:
-  - prepare-for-deploy
-  - deploy-to-service
-```
-
-## Use Travis-CI deployment tool
-We recommend to use **Dpl**. Dpl (dee-pee-ell) is a deploy tool made for continuous deployment that's developed and used by Travis CI, but can also be used with GitLab CI. You can read more information about it here: https://github.com/travis-ci/dpl.
+**We recommend to use Dpl, if you're deploying to any of these of these services: https://github.com/travis-ci/dpl#supported-providers**.
 
 ### Requirements
-To use `dpl` you need `ruby` at least 1.8.7 with ability to install `gems`.
+To use Dpl you need at least Ruby 1.8.7 with ability to install gems.
 
-### Installation
-The `dpl` can be installed on any machine with:
+### Basic usage
+The Dpl can be installed on any machine with:
 ```
 gem install dpl
 ```
 
-If you don't have Ruby installed you can do it on `Debian-compatible` `Linux` with:
+This allows you to test all commands from your shell, rather than having to test it on a CI server.
+
+If you don't have Ruby installed you can do it on Debian-compatible Linux with:
 ```
 apt-get update
 apt-get install ruby-dev
 ```
 
-What is also nice about `Dpl` is that you can install it on your computer and test all the commands from your Terminal without the need to test it on `CI` server.
-
-### How to use it?
-The `dpl` provides support for vast number of services, including: Heroku, Cloud Foundry, AWS/S3, and more. To use it simply define provider and any additional parameters required by the provider.
+The Dpl provides support for vast number of services, including: Heroku, Cloud Foundry, AWS/S3, and more. To use it simply define provider and any additional parameters required by the provider.
 
 For example if you want to use it to deploy your application to heroku, you need to specify `heroku` as provider, specify `api-key` and `app`. There's more and all possible parameters can be found here: https://github.com/travis-ci/dpl#heroku
 
@@ -42,13 +31,27 @@ staging:
   - dpl --provider=heroku --app=my-app-staging --api-key=$HEROKU_STAGING_API_KEY
 ```
 
-In the above example we use `dpl` to deploy `my-app-staging` to Heroku server with api-key stored in `HEROKU_STAGING_API_KEY` secure variable.
+In the above example we use Dpl to deploy `my-app-staging` to Heroku server with api-key stored in `HEROKU_STAGING_API_KEY` secure variable.
 
-### Use different provider
-Tu use different provider take a look at long list of [Supported Providers](https://github.com/travis-ci/dpl#supported-providers).
+To use different provider take a look at long list of [Supported Providers](https://github.com/travis-ci/dpl#supported-providers).
 
-### How to use it to have staging and production environment?
-It's pretty common in developer workflow to have staging (-dev) and production environment. If we consider above example: we would like to deploy `master` branch to `staging` and `all tags` to `production environment`. The final `.gitlab-ci.yml` for such setup would look like this:
+### Using Dpl with Docker
+When you use GitLab Runner you most likely configured it to use your server's shell commands. This means that all commands are run in context of local user (ie. gitlab_runner or gitlab_ci_multi_runner). It also means that most probably in your Docker container you don't have the Ruby runtime installed. You will have to install it:
+```
+staging:
+  type: deploy
+  - apt-get update -yq
+  - apt-get install -y ruby-dev
+  - gem install dpl
+  - dpl --provider=heroku --app=my-app-staging --api-key=$HEROKU_STAGING_API_KEY
+  only:
+  - master
+```
+
+The first line `apt-get update -yq` updates the list of available packages, where second `apt-get install -y ruby-dev` install `Ruby` runtime on system. The above example is valid for all Debian-compatible systems.
+
+### Usage in staging and production
+It's pretty common in developer workflow to have staging (development) and production environment. If we consider above example: we would like to deploy `master` branch to `staging` and `all tags` to `production` environment. The final `.gitlab-ci.yml` for that setup would look like this:
 
 ```
 staging:
@@ -66,7 +69,7 @@ production:
   - tags
 ```
 
-We basically created two deploy jobs that are execute for different events:
+We created two deploy jobs that are executed on different events:
 1. `staging` is executed for all commits that were pushed to `master` branch,
 2. `production` is executed for all pushed tags.
 
@@ -74,24 +77,14 @@ We also use two secure variables:
 1. `HEROKU_STAGING_API_KEY` - Heroku API key used to deploy staging app,
 2. `HEROKU_PRODUCTION_API_KEY` - Heroku API key used to deploy production app.
 
-### The way to store API keys?
-In GitLab CI 7.12 a new feature was introduced: Secure Variables. Secure Variables can added by going to `Project > Variables > Add Variable`. **This feature requires `gitlab-runner` with version equal or greater than 0.4.0.** The variable defined in project settings are send with build script to runner and set before executing script. What is important that such variable is stored outside of the project's repository. You should never store secrets in your project's `.gitlab-ci.yml`!  What is also important that it's value is hidden in the build log.
+### Storing API keys
+In GitLab CI 7.12 a new feature was introduced: Secure Variables.
+Secure Variables can added by going to `Project > Variables > Add Variable`. 
+**This feature requires `gitlab-runner` with version equal or greater than 0.4.0.**
+The variables that are defined in the project settings are send along with the build script to the runner.
+The secure variables are stored out of the repository. Never store secrets in your projects' .gitlab-ci.yml.
+It is also important that secret's value is hidden in the build log.
 
 You access added variable by prefixing it's name with `$` (on non-Windows runners) or `%` (for Windows Batch runners):
 1. `$SECRET_VARIABLE` - use it for non-Windows runners
 2. `%SECRET_VARIABLE%` - use it for Windows Batch runners
-
-### Using `dpl` with `Docker`
-When you use `runner` you most likely configured it to use your server's shell commands. This means that all commands are run in context of local user (ie. gitlab_runner or gitlab_ci_multi_runner). It also means that most probably in your `Docker` container you don't have the `Ruby` runtime. You have to install it:
-```
-staging:
-  type: deploy
-  - apt-get update -yq
-  - apt-get install -y ruby-dev
-  - gem install dpl
-  - dpl --provider=heroku --app=my-app-staging --api-key=$HEROKU_STAGING_API_KEY
-  only:
-  - master
-```
-
-The first line `apt-get update -yq` updates the list of available packages, where second `apt-get install -y ruby-dev` install `Ruby` runtime on system. The above example is valid for all Debian-compatible systems.
diff --git a/doc/examples/test-and-deploy-python-application-to-heroku.md b/doc/examples/test-and-deploy-python-application-to-heroku.md
index 0a9b9d7..162fd7e 100644
--- a/doc/examples/test-and-deploy-python-application-to-heroku.md
+++ b/doc/examples/test-and-deploy-python-application-to-heroku.md
@@ -1,6 +1,7 @@
-### Test and Deploy Python application to Heroku
-Example Python application with tests on PostgreSQL database, staging and production deployment to Heroku can be found here:
-[source](https://gitlab.com/ayufan/python-getting-started) and here: [ci](https://ci.gitlab.com/projects/4080)
+## Test and Deploy Python application to Heroku
+This example will guide you how to run tests in your Python application and deploy it automatiacally to staging and production Heroku application.
+
+You can check the [source](https://gitlab.com/ayufan/python-getting-started) and [CI status](https://ci.gitlab.com/projects/4080).
 
 ### Configure project
 This is how the configuration (the `.gitlab-ci.yml`) for that project looks like:
@@ -35,23 +36,23 @@ production:
   - tags
 ```
 
-This project have three jobs:
+This project has three jobs:
 1. `test` - used to test rails application,
 2. `staging` - used to automatically deploy staging environment every push to `master` branch
 3. `production` - used to automatically deploy production environmnet for every created tag
 
 ### Store API keys
-The project requires to create two secure variables in `Project > Variables`:
+You'll need to create two variables in `Project > Variables`:
 1. `HEROKU_STAGING_API_KEY` - Heroku API key used to deploy staging app,
 2. `HEROKU_PRODUCTION_API_KEY` - Heroku API key used to deploy production app.
 
-Heroku API key can be found in [Manage Account](https://dashboard.heroku.com/account).
+Find your Heroku API key in [Manage Account](https://dashboard.heroku.com/account).
 
 ### Create Heroku application
-You have to navigate to Heroku [Dashboard](https://dashboard.heroku.com/) and create new application to each of your environments.
+For each of your environments, you'll need to create a new Heroku application. You can do this through the [Dashboard](https://dashboard.heroku.com/).
 
 ### Create runner
-To build this project you also need to have `Runner`. You can use public runners available on `ci.gitlab.com`, but you can also provide your own:
+First install [Docker Engine](https://docs.docker.com/installation/). To build this project you also need to have [GitLab Runner](https://about.gitlab.com/gitlab-ci/#gitlab-runner). You can use public runners available on `ci.gitlab.com`, but you can register your own:
 ```
 gitlab-ci-multi-runner register \
   --non-interactive \
@@ -63,6 +64,6 @@ gitlab-ci-multi-runner register \
   --docker-postgres latest
 ```
 
-Above command creates runner that uses `docker` (you need to have Docker installed), uses [python:3.2](https://registry.hub.docker.com/u/library/python/) image and uses [postgres](https://registry.hub.docker.com/u/library/postgres/) database.
+Above command creates runner that uses [Docker](https://docker.com/), uses [python:3.2](https://registry.hub.docker.com/u/library/python/) image and uses [postgres](https://registry.hub.docker.com/u/library/postgres/) database.
 
-To access PostgreSQL database you need to connect to `host: postgres` instead of default: `localhost` as `postgres` user without password.
+To access PostgreSQL database you need to connect to `host: postgres` as user `postgres` without password.
diff --git a/doc/examples/test-and-deploy-ruby-application-to-heroku.md b/doc/examples/test-and-deploy-ruby-application-to-heroku.md
index 91d52d0..b94307f 100644
--- a/doc/examples/test-and-deploy-ruby-application-to-heroku.md
+++ b/doc/examples/test-and-deploy-ruby-application-to-heroku.md
@@ -1,6 +1,7 @@
-## Test and Deploy Ruby application to Heroku
-Example Ruby application with tests on PostgreSQL database, staging and production deployment to Heroku can be found here:
-[source](https://gitlab.com/ayufan/ruby-getting-started) and here: [ci](https://ci.gitlab.com/projects/4050)
+## Test and Deploy Python application to Heroku
+This example will guide you how to run tests in your Python application and deploy it automatiacally to staging and production Heroku application.
+
+You can check the [source](https://gitlab.com/ayufan/ruby-getting-started) and [CI status](https://ci.gitlab.com/projects/4050).
 
 ### Configure project
 This is how the configuration (the `.gitlab-ci.yml`) for that project looks like:
@@ -30,23 +31,23 @@ production:
   - tags
 ```
 
-This project have three jobs:
+This project has three jobs:
 1. `test` - used to test rails application,
 2. `staging` - used to automatically deploy staging environment every push to `master` branch
 3. `production` - used to automatically deploy production environmnet for every created tag
 
 ### Store API keys
-The project requires to create two secure variables in `Project > Variables`:
+You'll need to create two variables in `Project > Variables`:
 1. `HEROKU_STAGING_API_KEY` - Heroku API key used to deploy staging app,
 2. `HEROKU_PRODUCTION_API_KEY` - Heroku API key used to deploy production app.
 
-Heroku API key can be found in [Manage Account](https://dashboard.heroku.com/account).
+Find your Heroku API key in [Manage Account](https://dashboard.heroku.com/account).
 
 ### Create Heroku application
-You have to navigate to Heroku [Dashboard](https://dashboard.heroku.com/) and create new application to each of your environments.
+For each of your environments, you'll need to create a new Heroku application. You can do this through the [Dashboard](https://dashboard.heroku.com/).
 
 ### Create runner
-To build this project you also need to have `Runner`. You can use public runners available on `ci.gitlab.com`, but you can also provide your own:
+First install [Docker Engine](https://docs.docker.com/installation/). To build this project you also need to have [GitLab Runner](https://about.gitlab.com/gitlab-ci/#gitlab-runner). You can use public runners available on `ci.gitlab.com`, but you can register your own:
 ```
 gitlab-ci-multi-runner register \
   --non-interactive \
@@ -54,10 +55,10 @@ gitlab-ci-multi-runner register \
   --registration-token "PROJECT_REGISTRATION_TOKEN" \
   --description "ruby-2.1" \
   --executor "docker" \
-  --docker-image ruby:2.1 \
+  --docker-image python:2.1 \
   --docker-postgres latest
 ```
 
-Above command creates runner that uses `docker` (you need to have Docker installed), uses [ruby:2.1](https://registry.hub.docker.com/u/library/ruby/) image and uses [postgres](https://registry.hub.docker.com/u/library/postgres/) database.
+Above command creates runner that uses [Docker](https://docker.com/), uses [ruby:2.1](https://registry.hub.docker.com/u/library/ruby/) image and uses [postgres](https://registry.hub.docker.com/u/library/postgres/) database.
 
-To access PostgreSQL database you need to connect to `host: postgres` instead of default: `localhost` as `postgres` user without password.
+To access PostgreSQL database you need to connect to `host: postgres` as user `postgres` without password.