Merge branch 'grammar-tweaks' into 'master'

doc/ci/yaml/README.md

@@ -167,7 +167,7 @@ There are also two edge cases worth mentioning:
 
 1. If no `stages` is defined in `.gitlab-ci.yml`, then by default the `build`,
    `test` and `deploy` are allowed to be used as job's stage by default.
-2. If a job doesn't specify `stage`, the job is assigned the `test` stage.
+2. If a job doesn't specify a `stage`, the job is assigned the `test` stage.
 
 ### types
 
@@ -178,9 +178,9 @@ Alias for [stages](#stages).
 >**Note:**
 Introduced in GitLab Runner v0.5.0.
 
-GitLab CI allows you to add to `.gitlab-ci.yml` variables that are set in build
-environment. The variables are stored in the git repository and are meant to
-store non-sensitive project configuration, for example:
+GitLab CI allows you to add variables to `.gitlab-ci.yml` that are set in the
+build environment. The variables are stored in the git repository and are meant
+to store non-sensitive project configuration, for example:
 
 ```yaml
 variables:
@@ -253,8 +253,8 @@ rspec:
     - binaries/
 ```
 
-The cache is provided on best effort basis, so don't expect that cache will be
-always present. For implementation details please check GitLab Runner.
+The cache is provided on a best-effort basis, so don't expect that the cache
+will be always present. For implementation details, please check GitLab Runner.
 
 #### cache:key
 
@@ -479,10 +479,10 @@ failure.
 `when` can be set to one of the following values:
 
 1. `on_success` - execute build only when all builds from prior stages
-    succeeded. This is the default.
+    succeed. This is the default.
 1. `on_failure` - execute build only when at least one build from prior stages
-    failed.
-1. `always` - execute build despite the status of builds from prior stages.
+    fails.
+1. `always` - execute build regardless of the status of builds from prior stages.
 
 For example:
 
@@ -559,10 +559,10 @@ The `deploy to production` job will be marked as doing deployment to `production
 > - Introduced in GitLab Runner v0.7.0 for non-Windows platforms.
 > - Windows support was added in GitLab Runner v.1.0.0.
 > - Currently not all executors are supported.
-> - Build artifacts are only collected for successful builds.
+> - Build artifacts are only collected for successful builds by default.
 
-`artifacts` is used to specify list of files and directories which should be
-attached to build after success. To pass artifacts between different builds,
+`artifacts` is used to specify a list of files and directories which should be
+attached to the build after success. To pass artifacts between different builds,
 see [dependencies](#dependencies).
 
 Below are some examples.
@@ -690,9 +690,9 @@ failure.
 
 `artifacts:when` can be set to one of the following values:
 
-1. `on_success` - upload artifacts only when build succeeds. This is the default
-1. `on_failure` - upload artifacts only when build fails
-1. `always` - upload artifacts despite the build status
+1. `on_success` - upload artifacts only when the build succeeds. This is the default.
+1. `on_failure` - upload artifacts only when the build fails.
+1. `always` - upload artifacts regardless of the build status.
 
 ---
 
@@ -711,16 +711,18 @@ job:
 >**Note:**
 Introduced in GitLab 8.9 and GitLab Runner v1.3.0.
 
-`artifacts:expire_in` is used to remove uploaded artifacts after specified time.
-By default artifacts are stored on GitLab forver.
-`expire_in` allows to specify after what time the artifacts should be removed.
-The artifacts will expire counting from the moment when they are uploaded and stored on GitLab.
+`artifacts:expire_in` is used to delete uploaded artifacts after the specified
+time. By default, artifacts are stored on GitLab forever. `expire_in` allows you
+to specify how long artifacts should live before they expire, counting from the
+time they are uploaded and stored on GitLab.
 
-After artifacts uploading you can use the **Keep** button on build page to keep the artifacts forever.
+You can use the **Keep** button on the build page to override expiration and
+keep artifacts forever.
 
-Artifacts are removed every hour, but they are not accessible after expire date.
+By default, artifacts are deleted hourly (via a cron job), but they are not
+accessible after expiry.
 
-The value of `expire_in` is a elapsed time. The example of parsable values:
+The value of `expire_in` is an elapsed time. Examples of parseable values:
 - '3 mins 4 sec'
 - '2 hrs 20 min'
 - '2h20min'
@@ -732,7 +734,7 @@ The value of `expire_in` is a elapsed time. The example of parsable values:
 
 **Example configurations**
 
-To expire artifacts after 1 week from the moment that they are uploaded:
+To expire artifacts 1 week after being uploaded:
 
 ```yaml
 job: