Fixes a bunch of spelling/grammar mistakes.

There were many spelling mistakes, which ultimately distracted
from the content it was describing. This commit fixes all that
I could find, and rewords some sentences to improve clarity

1 files changed, 32 insertions, 30 deletions

diff --git a/doc/yaml/README.md b/doc/yaml/README.md
index 6600988..67e5ac1 100644
--- a/doc/yaml/README.md
+++ b/doc/yaml/README.md
@@ -1,9 +1,10 @@
 # Configuration of your builds with .gitlab-ci.yml
 From version 7.12, GitLab CI uses a [YAML](https://en.wikipedia.org/wiki/YAML) file (**.gitlab-ci.yml**) for the project configuration.
-It is placed in the root of your repository and contains definition how project should be built.
+It is placed in the root of your repository and contains definitions of how your project should be built.
+
+The YAML file defines a set of jobs with constraints stating when they should be run.
+The jobs are defined as top-level elements with a name and always have to contain the `script` clause:
 
-The YAML defines set of jobs with constrains when they should be run.
-The jobs are defined as top-level elements with name and always have to contain the `script`: 
 ```yaml
 job1:
   script: "execute-script-for-job1"
@@ -13,13 +14,14 @@ job2:
 ```
 
 The above example is the simplest possible CI configuration with two separate jobs,
-where each of the job executes different script.
+where each of the jobs executes a different 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. 
+Jobs are used to create builds, which are then picked up by [runners](../runners/README.md) and executed within the environment of the runner.
+What is important, is that each job is run independently from each other.
 
 ## .gitlab-ci.yml
-The YAML syntax allows to use more complex jobs specification then above example:
+The YAML syntax allows for using more complex job specifications than in the above example:
+
 ```yaml
 image: ruby:2.1
 services:
@@ -53,22 +55,22 @@ There are a few `keywords` that can't be used as job names:
 | before_script | optional | Define commands prepended for each job's script |
 
 ### image and services
-This allows to specify custom Docker image and list of services that can be used for time of the build.
+This allows to specify a custom Docker image and a list of services that can be used for time of the build.
 The configuration of this feature is covered in separate document: [Use Docker](../docker/README.md).
 
 ### before_script
-`before_script` is used to define the command that should be ran before all builds, including deploy builds. This can be an array or a multiline string
+`before_script` is used to define the command that should be run before all builds, including deploy builds. This can be an array or a multiline string.
 
 ### types
 `types` is used to define build types that can be used by jobs.
-The specification of `types` allow to have flexible multi stage pipeline. 
+The specification of `types` allows for having flexible multi stage pipelines.
 
-The ordering of elements in `types` defines the ordering of builds execution:
+The ordering of elements in `types` defines the ordering of builds' execution:
 
-1. Builds of the same type are run in parallel. 
+1. Builds of the same type are run in parallel.
 1. Builds of next type are run after success.
 
-Let's consider following example that defines 3 types:
+Let's consider the following example, which defines 3 types:
 ```
 types:
   - build
@@ -80,17 +82,17 @@ types:
 1. If all jobs of `build` succeeds, the `test` jobs are executed in parallel.
 1. If all jobs of `test` succeeds, the `deploy` jobs are executed in parallel.
 1. If all jobs of `deploy` succeeds, the commit is marked as `success`.
-1. If any of the previous jobs fails the commit is marked as `failed` and no jobs of further type is executed.
+1. If any of the previous jobs fails, the commit is marked as `failed` and no jobs of further type are executed.
 
 There are also two edge cases worth mentioning:
 
-1. If no `types` is defined in `.gitlab-ci.yml` by default: build, test and deploy is allowed to be used as job's type.
-2. If job doesn't specify `type`, the job is assigned to `test`.
+1. If no `types` is defined in `.gitlab-ci.yml`, then the types `build`, `test` and `deploy` are allowed to be used as job's type by default.
+2. If a job doesn't specify `type`, the job is assigned the `test` type.
 
 ## Jobs
-`.gitlab-ci.yml` allows to specify unlimited number of jobs.
-Each job has to have unique `job_name`, that is not the one of the keywords. 
-Job is defined by a list of parameters that define the build behaviour.
+`.gitlab-ci.yml` allows you to specify an unlimited number of jobs.
+Each job has to have a unique `job_name`, which is not one of the keywords mentioned above.
+A job is defined by a list of parameters that define the build behaviour.
 
 ```yaml
 job_name:
@@ -125,7 +127,7 @@ job:
   script: "bundle exec rspec"
 ```
 
-This parameter can also contain several commands using array:
+This parameter can also contain several commands using an array:
 ```yaml
 job:
   script:
@@ -138,15 +140,15 @@ job:
 For more info about the use of `type` please check the [types](#types).
 
 ### only and except
-This are two parameters that allows to set refs policy to limit when jobs are built:
-1. `only` defines the names of branches and tags for which job will be build.
-2. `except` defines the names of branches and tags that will be excluded from building specific job.
+This are two parameters that allow for setting a refs policy to limit when jobs are built:
+1. `only` defines the names of branches and tags for which job will be built.
+2. `except` defines the names of branches and tags for which the job wil **not** be built.
 
 There are a few rules that apply to usage of refs policy:
 
 1. `only` and `except` are exclusive. If both `only` and `except` are defined in job specification only `only` is taken into account.
-1. `only` and `except` allows to use the regexp expressions.
-1. `only` and `except` allows to use special keywords: `branches` and `tags`.
+1. `only` and `except` allow for using the regexp expressions.
+1. `only` and `except` allow for using special keywords: `branches` and `tags`.
 These names can be used for example to exclude all tags and all branches.
 
 ```yaml
@@ -158,10 +160,10 @@ job:
 ```
 
 ### tags
-`tags` is used to select specific runner from the list of all runners that are allowed to run this project.
+`tags` is used to select specific runners from the list of all runners that are allowed to run this project.
 
-During registration of runner you can specify runner's tags, ie.: `ruby`, `postgres`, `development`.
-`tags` allows you to run builds by runners that have the specified tags assigned:
+During registration of a runner, you can specify the runner's tags, ie.: `ruby`, `postgres`, `development`.
+`tags` allow you to run builds with runners that have the specified tags assigned:
 
 ```
 job:
@@ -170,10 +172,10 @@ job:
     - postgres
 ```
 
-The above specification will make sure that `job` is built by runner that have `ruby` AND `postgres` tags defined.
+The above specification will make sure that `job` is built by a runner that have `ruby` AND `postgres` tags defined.
 
 ## Validate the .gitlab-ci.yml
-Each instance of GitLab CI has an embedded debug tool Lint.
+Each instance of GitLab CI has an embedded debug tool called Lint.
 You can find the link to the Lint in the project's settings page or use short url `/lint`.
 
 ## Skipping builds