Incorporate Brendan's feedback

2 files changed, 32 insertions, 32 deletions

diff --git a/doc/ci/README.md b/doc/ci/README.md
index 4c47bf9f8b0..d4608afb8e7 100644
--- a/doc/ci/README.md
+++ b/doc/ci/README.md
@@ -5,10 +5,10 @@ description: "Learn how to use GitLab CI/CD, the GitLab built-in Continuous Inte
 
 # GitLab Continuous Integration (GitLab CI/CD)
 
-GitLab provides tools for continuously integrating and delivering code hosted in [projects](../user/project/index.md).
+GitLab provides tools for continuously integrating and delivering code.
 
 Within the [entire DevOps lifecycle](../README.md#the-entire-devops-lifecycle), GitLab CI/CD spans
-the [Verify](../README.md#verify) and [Release](../README.md#release) stages.
+the [Verify (CI)](../README.md#verify) and [Release (CD)](../README.md#release) stages.
 
 For a high-level overview, see the
 [GitLab Continuous Integration & Delivery](https://about.gitlab.com/product/continuous-integration/)
@@ -39,16 +39,16 @@ links to topics and resources needed to make use of GitLab CI/CD.
 
 The following documentation provides the minimum required knowledge for making use of GitLab CI/CD:
 
-| Topic                                                              | Description                                              |
-|:-------------------------------------------------------------------|:---------------------------------------------------------|
-| [Getting started with GitLab CI/CD](quick_start/README.md)         | Outlines the first steps for configuring GitLab CI/CD.   |
-| [Configuration of your jobs with `.gitlab-ci.yml`](yaml/README.md) | A comprehensive reference for the `.gitlab-ci.yml` file. |
-| [Introduction to pipelines and jobs](pipelines.md)                 | Introduces GitLab CI/CD pipelines.                       |
+| Topic                                                                   | Description                                              |
+|:------------------------------------------------------------------------|:---------------------------------------------------------|
+| [Getting started with GitLab CI/CD](quick_start/README.md)              | Outlines the first steps for configuring GitLab CI/CD.   |
+| [Introduction to pipelines and jobs](pipelines.md)                      | Provides an overview of GitLab CI/CD and jobs.           |
+| [Configuration of your pipelines with `.gitlab-ci.yml`](yaml/README.md) | A comprehensive reference for the `.gitlab-ci.yml` file. |
 
 NOTE: **Note:**
 Familiarity with [GitLab Runner](https://docs.gitlab.com/runner/) is useful because it is
 responsible for running the jobs in your CI/CD pipeline. On GitLab.com, shared Runners are enabled
-by default so you don't need to set up anything.
+by default so you don't need to set up anything to get started.
 
 ### Auto DevOps
 
@@ -93,6 +93,11 @@ use of advanced features:
 GitLab CI/CD can be used to build and host static websites. For more information, see the
 documentation on [GitLab Pages](../user/project/pages/index.md).
 
+## Examples
+
+Check out the [GitLab CI/CD examples](examples/README.md) for a collection of tutorials and guides on
+setting up your CI/CD pipeline for various programming languages, frameworks, and operating systems.
+
 ## Administration
 
 As a GitLab administrator, you can change the default behavior of GitLab CI/CD for:
@@ -127,37 +132,37 @@ This section provides further resources to help you get familiar with GitLab CI/
 
 ### Articles
 
-The following table provides a list of articles, sorted by publish date:
+The following table provides a list of articles about CI/CD, sorted in reverse chronological order of publish date:
 
 | Publish Date | Article                                                                                                                                                                                                                                       |
 |:-------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| 2015-12-14   | [Getting started with GitLab and GitLab CI](https://about.gitlab.com/2015/12/14/getting-started-with-gitlab-and-gitlab-ci/).                                                                                                                  |
-| 2015-03-01   | [Setting up GitLab Runner For Continuous Integration](https://about.gitlab.com/2016/03/01/gitlab-runner-with-docker/).                                                                                                                        |
-| 2016-04-19   | [GitLab Partners with DigitalOcean to make Continuous Integration faster, safer, and more affordable](https://about.gitlab.com/2016/04/19/gitlab-partners-with-digitalocean-to-make-continuous-integration-faster-safer-and-more-affordable/) |
-| 2016-05-05   | [Getting Started with GitLab and Shippable Continuous Integration](https://about.gitlab.com/2016/05/05/getting-started-gitlab-and-shippable/)                                                                                                 |
-| 2016-05-23   | [GitLab Container Registry](https://about.gitlab.com/2016/05/23/gitlab-container-registry/).                                                                                                                                                  |
-| 2016-06-09   | [Continuous Delivery with GitLab and Convox](https://about.gitlab.com/2016/06/09/continuous-delivery-with-gitlab-and-convox/)                                                                                                                 |
-| 2016-07-29   | [GitLab CI: Run jobs sequentially, in parallel or build a custom pipeline](https://about.gitlab.com/2016/07/29/the-basics-of-gitlab-ci/).                                                                                                     |
-| 2016-08-05   | [Continuous Integration, Delivery, and Deployment with GitLab](https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/).                                                                              |
-| 2016-08-26   | [GitLab CI: Deployment & Environments](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/).                                                                                                                                  |
-| 2016-11-22   | [Introducing Review Apps](https://about.gitlab.com/2016/11/22/introducing-review-apps/).                                                                                                                                                      |
-| 2017-05-22   | [Fast and natural continuous integration with GitLab CI](https://about.gitlab.com/2017/05/22/fast-and-natural-continuous-integration-with-gitlab-ci/).                                                                                        |
 | 2017-07-13   | [Making CI easier with GitLab](https://about.gitlab.com/2017/07/13/making-ci-easier-with-gitlab/).                                                                                                                                            |
+| 2017-05-22   | [Fast and natural continuous integration with GitLab CI](https://about.gitlab.com/2017/05/22/fast-and-natural-continuous-integration-with-gitlab-ci/).                                                                                        |
+| 2016-11-22   | [Introducing Review Apps](https://about.gitlab.com/2016/11/22/introducing-review-apps/).                                                                                                                                                      |
+| 2016-08-26   | [GitLab CI: Deployment & Environments](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/).                                                                                                                                  |
+| 2016-08-05   | [Continuous Integration, Delivery, and Deployment with GitLab](https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/).                                                                              |
+| 2016-07-29   | [GitLab CI: Run jobs sequentially, in parallel or build a custom pipeline](https://about.gitlab.com/2016/07/29/the-basics-of-gitlab-ci/).                                                                                                     |
+| 2016-06-09   | [Continuous Delivery with GitLab and Convox](https://about.gitlab.com/2016/06/09/continuous-delivery-with-gitlab-and-convox/)                                                                                                                 |
+| 2016-05-23   | [GitLab Container Registry](https://about.gitlab.com/2016/05/23/gitlab-container-registry/).                                                                                                                                                  |
+| 2016-05-05   | [Getting Started with GitLab and Shippable Continuous Integration](https://about.gitlab.com/2016/05/05/getting-started-gitlab-and-shippable/)                                                                                                 |
+| 2016-04-19   | [GitLab Partners with DigitalOcean to make Continuous Integration faster, safer, and more affordable](https://about.gitlab.com/2016/04/19/gitlab-partners-with-digitalocean-to-make-continuous-integration-faster-safer-and-more-affordable/) |
+| 2015-03-01   | [Setting up GitLab Runner For Continuous Integration](https://about.gitlab.com/2016/03/01/gitlab-runner-with-docker/).                                                                                                                        |
+| 2015-12-14   | [Getting started with GitLab and GitLab CI](https://about.gitlab.com/2015/12/14/getting-started-with-gitlab-and-gitlab-ci/).                                                                                                                  |
 
 ### Videos
 
-The following table provides a list of videos, sorted by publish date:
+The following table provides a list of videos about CI/CD, sorted in reverse chronological order of publish date:
 
 | Publish Date | Video                                                                                                                                                              |
 |:-------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| 2016-04-20   | [Webcast Recording and Slides: Getting started with CI in GitLab](https://about.gitlab.com/2016/04/20/webcast-recording-and-slides-introduction-to-ci-in-gitlab/). |
-| 2017-03-13   | [Demo: CI/CD with GitLab in action](https://about.gitlab.com/2017/03/13/ci-cd-demo/).                                                                              |
 | 2017-07-17   | [GitLab CI/CD Deep Dive](https://youtu.be/pBe4t1CD8Fc?t=195).                                                                                                      |
+| 2017-03-13   | [Demo: CI/CD with GitLab in action](https://about.gitlab.com/2017/03/13/ci-cd-demo/).                                                                              |
+| 2016-04-20   | [Webcast Recording and Slides: Getting started with CI in GitLab](https://about.gitlab.com/2016/04/20/webcast-recording-and-slides-introduction-to-ci-in-gitlab/). |
 
 In addition, the following third-party videos are available:
 
-- [GitLab CI for Minecraft Plugins (July 2016)](https://www.youtube.com/watch?v=Z4pcI9F8yf8).
 - [Intégration continue avec GitLab (September 2016)](https://www.youtube.com/watch?v=URcMBXjIr24&t=13s).
+- [GitLab CI for Minecraft Plugins (July 2016)](https://www.youtube.com/watch?v=Z4pcI9F8yf8).
 
 ### Example Projects
 
@@ -169,16 +174,11 @@ Other example projects are available at the [`gitlab-examples`](https://gitlab.c
 
 The following articles explain reasons why you might use GitLab CI/CD for your CI/CD infrastructure:
 
-- [Building our web-app on GitLab CI](https://about.gitlab.com/2016/07/22/building-our-web-app-on-gitlab-ci/).
 - [Why we chose GitLab CI for our CI/CD solution](https://about.gitlab.com/2016/10/17/gitlab-ci-oohlala/).
+- [Building our web-app on GitLab CI](https://about.gitlab.com/2016/07/22/building-our-web-app-on-gitlab-ci/).
 
 See also the [Why CI/CD?](https://docs.google.com/presentation/d/1OGgk2Tcxbpl7DJaIOzCX4Vqg3dlwfELC3u2jEeCBbDk) presentation.
 
-## Examples
-
-Check out the [GitLab CI/CD examples](examples/README.md) for a collection of tutorials and guides on
-setting up your CI/CD pipeline for various programming languages, frameworks, and operating systems.
-
 ## Breaking changes
 
 As GitLab CI/CD has evolved, certain breaking changes have been necessary. These are:
diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index 8c8a31e9323..352776a5042 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -1,7 +1,7 @@
-# Configuration of your jobs with .gitlab-ci.yml
+# Configuration of your pipelines with .gitlab-ci.yml
 
 This document describes the usage of `.gitlab-ci.yml`, the file that is used by
-GitLab Runner to manage your project's jobs.
+GitLab Runner to manage your project's pipelines.
 
 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