Add definitions and tweak some docs. Partially fixes #17733

4 files changed, 67 insertions, 14 deletions

diff --git a/doc/ci/README.md b/doc/ci/README.md
index 5a1cb5319c6..c7a29e269b5 100644
--- a/doc/ci/README.md
+++ b/doc/ci/README.md
@@ -3,6 +3,7 @@
 ### CI User documentation
 
 - [Get started with GitLab CI](quick_start/README.md)
+- [CI/CD Definitions](definitions/README.md)
 - [CI examples for various languages](examples/README.md)
 - [Learn how to enable or disable GitLab CI](enable_or_disable_ci.md)
 - [Environments and deployments](environments.md)
diff --git a/doc/ci/definitions/README.md b/doc/ci/definitions/README.md
new file mode 100644
index 00000000000..4ec5eee5757
--- /dev/null
+++ b/doc/ci/definitions/README.md
@@ -0,0 +1,52 @@
+## CI/CD Definitions
+
+### Pipelines
+
+A pipeline is a group of [builds] that get executed in [stages] (batches). All of
+the builds in a stage are executed in parallel (if there are enough concurrent
+[runners]), and if they all succeed, the pipeline moves on to the next stage. If
+one of the builds fails, the next stage is not (usually) executed.
+
+### Builds
+
+Builds are runs of [jobs]. Not to be confused with a `build` stage.
+
+### Jobs
+
+Jobs are the basic work unit of CI/CD. Jobs are used to create [builds], which are
+then picked up by [Runners] and executed within the environment of the Runner.
+Each job is run independently from each other.
+
+### Runners
+
+A runner is an isolated (virtual) machine that picks up builds through the
+coordinator API of GitLab CI. 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.
+
+### Stages
+
+Stages allow [jobs] to be grouped into parallel and sequential [builds]. Builds
+of the same stage are executed in parallel and builds of the next stage are run
+after the jobs from the previous stage complete successfully. Stages allow for
+flexible multi-stage [pipelines]. By default [pipelines] have `build`, `test`
+and `deploy` stages, but these can be defined in `.gitlab-ci.yml`. If a job
+doesn't specify a stage, the job is assigned to the test stage.
+
+### Environments
+
+Environments are places where code gets deployed, such as staging or production.
+CI/CD [Pipelines] usually have one or more deploy stages with [jobs] that do
+[deployments] to an environment.
+
+### Deployments
+
+Deployments are created when [jobs] deploy versions of code to [environments].
+
+[pipelines]: #pipelines
+[builds]: #builds
+[runners]: #runners
+[jobs]: #jobs
+[stages]: #stages
+[environments]: #environments
+[deployments]: #deployments
diff --git a/doc/ci/quick_start/README.md b/doc/ci/quick_start/README.md
index 386b8e29fcf..07fbefa0416 100644
--- a/doc/ci/quick_start/README.md
+++ b/doc/ci/quick_start/README.md
@@ -4,41 +4,40 @@
 is fully integrated into GitLab itself and is [enabled] by default on all
 projects.
 
-The TL;DR version of how GitLab CI works is the following.
-
----
-
 GitLab offers a [continuous integration][ci] service. If you
 [add a `.gitlab-ci.yml` file][yaml] to the root directory of your repository,
 and configure your GitLab project to use a [Runner], then each merge request or
-push triggers a build.
+push triggers your CI [pipeline].
 
 The `.gitlab-ci.yml` file tells the GitLab runner what to do. By default it
-runs three [stages]: `build`, `test`, and `deploy`.
+runs a pipeline with three [stages]: `build`, `test`, and `deploy`.
 
 If everything runs OK (no non-zero return values), you'll get a nice green
 checkmark associated with the pushed commit or merge request. This makes it
-easy to see whether a merge request will cause any of the tests to fail before
+easy to see whether a merge request caused any of the tests to fail before
 you even look at the code.
 
-Most projects only use GitLab's CI service to run the test suite so that
+Most projects use GitLab's CI service to run the test suite so that
 developers get immediate feedback if they broke something.
 
+There's a growing trend to use continuous delivery and continuous deployment to
+automatically deploy tested code to staging and production environments.
+
 So in brief, the steps needed to have a working CI can be summed up to:
 
 1. Add `.gitlab-ci.yml` to the root directory of your repository
 1. Configure a Runner
 
-From there on, on every push to your Git repository, the build will be
-automagically started by the Runner and will appear under the project's
-`/builds` page.
+From there on, on every push to your Git repository, the Runner will
+automagically start the pipeline and the pipeline will appear under the
+project's `/pipelines` page.
 
 ---
 
 This guide assumes that you:
 
 - have a working GitLab instance of version 8.0 or higher or are using
-  [GitLab.com](https://gitlab.com/users/sign_in)
+  [GitLab.com](https://gitlab.com)
 - have a project in GitLab that you would like to use CI for
 
 Let's break it down to pieces and work on solving the GitLab CI puzzle.
@@ -238,3 +237,4 @@ CI with various languages.
 [runner]: ../runners/README.md
 [enabled]: ../enable_or_disable_ci.md
 [stages]: ../yaml/README.md#stages
+[pipeline]: ../definitions/README.md#pipelines
diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index d0fbcbe9988..b134b5cd5d3 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -54,7 +54,7 @@ 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:
+to contain at least the `script` clause:
 
 ```yaml
 job1:
@@ -165,7 +165,7 @@ stages:
 
 There are also two edge cases worth mentioning:
 
-1. If no `stages` is defined in `.gitlab-ci.yml`, then by default the `build`,
+1. If no `stages` are 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 a `stage`, the job is assigned the `test` stage.