improve ci docs and integrate knowledge

2 files changed, 64 insertions, 51 deletions

diff --git a/doc/README.md b/doc/README.md
index e3fcb96..dc45f65 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -3,9 +3,9 @@
 ### User documentation
 
 + [Quick Start](quick_start/README.md)
-+ [Configuring project (.gitlab-ci.yml)](yaml/README.md)
-+ [Configuring runner](runners/README.md)
-+ [Configuring deployment](deployment/README.md)
++ [Configuring your projects with .gitlab-ci.yml](yaml/README.md)
++ [Configuring runners](runners/README.md)
++ [Configuring deployments](deployment/README.md)
 + [Using Docker Images](docker/using_docker_images.md)
 + [Using Docker Build](docker/using_docker_build.md)
 + [Using Variables](variables/README.md)
diff --git a/doc/quick_start/README.md b/doc/quick_start/README.md
index 3b9156f..dd9817c 100644
--- a/doc/quick_start/README.md
+++ b/doc/quick_start/README.md
@@ -1,40 +1,38 @@
 # Quick Start
 
-To start building projects with GitLab CI a few steps needs to be done.
+GitLab Continuous Integration (CI) is a part of GitLab. This means you do not need
+to do any configuration to GitLab to enable CI.
 
-## 1. Install GitLab and CI
+To start using CI for any of your projects, simply follow the steps below.
 
-First you need to have a working GitLab and GitLab CI instance.
+This guide assumes you:
 
-You can omit this step if you use [GitLab.com](http://GitLab.com/).
+- have a working GitLab instance of version 8.0 or higher or are using GitLab.com
+- have a project in GitLab that you would like to use CI for
 
-## 2. Create repository on GitLab
+## 1. Creating a `.gitlab-ci.yml` file
 
-Once you login on your GitLab add a new repository where you will store your source code.
-Push your application to that repository.
+### What is it
 
-## 3. Add project to CI
+The `.gitlab-ci.yml` file is where you configure what CI does with your project.
+It lives in the root of your repository.
 
-The next part is to login to GitLab CI.
-Point your browser to the URL you have set GitLab CI or use [ci.gitlab.com](http://ci.gitlab.com/) that is linked to [GitLab.com](http://GitLab.com/).
+On any push to your repository, GitLab will look for the `.gitlab-ci.yml`
+file and start builds on _runners_ according to the contents of the file,
+for that commit.
 
-On the first screen you will see a list of GitLab's projects that you have access to:
+Because `.gitlab-ci.yml` is in the repository, it is version controlled,
+old versions still build succesfully, forks can easily make use of CI,
+branches can have separate builds and you have a single source of truth for CI.
+You can read more about the reasons why we are using `.gitlab-ci.yml`
+[in our blog about it](https://about.gitlab.com/2015/05/06/why-were-replacing-gitlab-ci-jobs-with-gitlab-ci-dot-yml/).
 
-![Projects](projects.png)
+`.gitlab-ci.yml` is a [YAML](https://en.wikipedia.org/wiki/YAML) file.
 
-Click **Add Project to CI**.
-This will create project in CI and authorize GitLab CI to fetch sources from GitLab.
+### Creating a simple `.gitlab-ci.yml` file
 
-> GitLab CI creates unique token that is used to configure GitLab CI service in GitLab.
-> This token allows to access GitLab's repository and configures GitLab to trigger GitLab CI webhook on **Push events** and **Tag push events**.
-> You can see that token by going to Project's Settings > Services > GitLab CI.
-> You will see there token, the same token is assigned in GitLab CI settings of project.
-
-## 4. Create project's configuration - .gitlab-ci.yml
-
-The next: You have to define how your project will be built.
-GitLab CI uses [YAML](https://en.wikipedia.org/wiki/YAML) file to store build configuration.
-You need to create `.gitlab-ci.yml` in root directory of your repository:
+You need to create `.gitlab-ci.yml` in root directory of your repository.
+Below an example for a Ruby on Rails project.
 
 ```yaml
 before_script:
@@ -56,11 +54,11 @@ This is the simplest possible build configuration that will work for most Ruby a
 The `.gitlab-ci.yml` defines set of jobs with constrains how and when they should be run.
 The jobs are defined as top-level elements with name and always have to contain the `script`.
 Jobs are used to create builds, which are then picked by [runners](../runners/README.md) and executed within environment of the runner.
-What is important that each job is run independently from each other. 
+What is important that each job is run independently from each other.
 
 For more information and complete `.gitlab-ci.yml` syntax, please check the [Configuring project (.gitlab-ci.yml)](../yaml/README.md).
 
-## 5. Add file and push .gitlab-ci.yml to repository
+### Push the file to GitLab
 
 Once you created `.gitlab-ci.yml` you should add it to git repository and push it to GitLab.
 
@@ -74,46 +72,61 @@ If you refresh the project's page on GitLab CI you will notice a one new commit:
 
 ![](new_commit.png)
 
-However the commit has status **pending** which means that commit was not yet picked by runner.
+The commit is still pending, as it has not yet been picked up by a runner.
 
-## 6. Configure runner
+## 2. Configuring a Runner
 
-In GitLab CI, Runners run your builds.
-A runner is a machine (can be virtual, bare-metal or VPS) that picks up builds through the coordinator API of GitLab CI.
+In GitLab, Runners run the builds that you define in `.gitlab-ci.yml`.
+A Runner can be a virtual machine, a VPS, a bare-metal machine, a docker container
+or even a cluster of containers.
+GitLab and the Runners communicate through an API.
 
-A runner can be specific to a certain project or serve any project in GitLab CI.
-A runner that serves all projects is called a shared runner.
-More information about different runner types can be found in [Configuring runner](../runners/README.md).
+A runner can be specific to a certain project or serve multiple projects in GitLab.
+A runner that serves all projects is called a _shared runner_.
+Find more information about different runners in [Configuring runners](../runners/README.md).
 
-To check if you have runners assigned to your project go to **Runners**. You will find there information how to setup project specific runner:
+You can find whether any Runners are assigned to your project by going to
+`Settings` and then `Runners`.
 
-1. Install GitLab Runner software. Checkout the [GitLab Runner](https://about.gitlab.com/gitlab-ci/#gitlab-runner) section to install it.
-1. Specify following URL during runner setup: https://ci.gitlab.com/
-1. Use the following registration token during setup: TOKEN
+Setting up a Runner is easy and straightforward. Simply follow the guide
+for the type of Runner you're planning to use:
+[Instructions for the various GitLab Runners](https://about.gitlab.com/gitlab-ci/#gitlab-runner)
 
-If you do it correctly your runner should be shown under **Runners activated for this project**:
+Once the Runner has been set up, you should see it on the Runners page of your
+project.
 
 ![](runners_activated.png)
 
 ### Shared runners
 
-If you use [ci.gitlab.com](http://ci.gitlab.com/) you can use **Shared runners** provided by GitLab Inc.
+If you use [GitLab.com](http://gitlab.com/) you can use **Shared runners** provided by GitLab Inc.
 These are special virtual machines that are run on GitLab's infrastructure that can build any project.
 To enable **Shared runners** you have to go to **Runners** and click **Enable shared runners** for this project.
 
-## 7. Check status of commit
+## 3. Seeing the status of your build
+
+After configuring the runner succesfully, you should see the status of your last
+commit change from _pending_ to either _running_, _success_ or _failed_.
 
-If everything went OK and you go to commit, the status of the commit should change from **pending** to either **running**, **success** or **failed**.
+You can view all builds, by going to **Builds** in your project.
+You are also able to view the status of any commit in the various pages in
+GitLab, such as **Commits* and **Merge Requests**.
 
 ![](commit_status.png)
 
-You can click **Build ID** to view build log for specific job.
+By clicking on a Build ID, you will be able to see the log of that build.
+This is important to diagnose why a build failed or acted differently than
+you expected.
+
+## Next steps
+
+Awesome! You started using CI in GitLab!
 
-## 8. Congratulations!
+Next you can look into doing more with the CI. Many people are using GitLab
+to package, containerize, test and deploy software.
 
-You managed to build your first project using GitLab CI.
-You may need to tune your `.gitlab-ci.yml` file to implement build plan for your project.
-A few examples how it can be done you can find on [Examples](../examples/README.md) page.
+We have a number of [examples]((../examples/README.md)) available.
 
-GitLab CI also offers **the Lint** tool to verify validity of your `.gitlab-ci.yml` which can be useful to troubleshoot potential problems.
-The Lint is available from project's settings or by adding `/lint` to GitLab CI url.
+If you want to check whether your `.gitlab-ci.yml` file is valid,
+visit the CI settings page under settings in your project. There you will
+find the Lint tool.