Copy-edit docs for cross-project pipelines

doc/ci/multi_project_pipelines.md

@@ -32,9 +32,7 @@ Let's assume you deploy your web app from different projects in GitLab:
 
 With Multi-Project Pipelines, you can visualize the entire pipeline, including all stages of builds and tests for the three projects.
 
-## How it works
-
-### Creating cross-project pipeline through API
+## Triggering cross-project pipeline through API
 
 When you use the [`CI_JOB_TOKEN` to trigger pipelines](triggers/README.md#ci-job-token), GitLab
 recognizes the source of the job token, and thus internally ties these pipelines
@@ -43,19 +41,19 @@ together, allowing you to visualize their relationships on pipeline graphs.
 These relationships are displayed in the pipeline graph by showing inbound and
 outbound connections for upstream and downstream pipeline dependencies.
 
-### Creating cross-project pipeline in .gitlab-ci.yml
+## Creating cross-project pipeline in .gitlab-ci.yml
 
 > Introduced in GitLab 11.8
 
-#### Triggering a downstream pipeline using a bridge job
+### Triggering a downstream pipeline using a bridge job
 
 Before GitLab 11.8 it was necessary to implement a pipeline job that was
-responsible for making the API request [to trigger a pipeline](triggers/README.md#ci-job-token)
+responsible for making the API request [to trigger a pipeline](triggers/README.md#creating-cross-project-pipeline-through-API)
 in a different project.
 
-In GitLab 11.8 we introduced a new CI/CD configuration syntax to make this task
-easier, and avoid the need of involving GitLab Runner in triggering a
-cross-project pipeline.
+In GitLab 11.8, GitLab provides a new CI/CD configuration syntax to make this
+task easier, and avoid needing GitLab Runner for triggering a cross-project
+pipelines.
 
 ```yaml
 rspec:
@@ -69,32 +67,33 @@ staging:
   trigger: my/deployment
 ```
 
-The example above, as soon as `rspec` job succeeds in stage `test`, `staging`
-_bridge_ job is going to be started. Initial status of this job is going to be
-`pending`. GitLab will create a downstream pipeline in the `my/deployment`
-project, and as soon as the pipeline gets created, `staging` job is going to
-succeed. `my/deployment` is a full path to that project.
+In the example above, as soon as `rspec` job succeeds in stage `test`,
+`staging` "bridge" job is going to be started. Initial status of this job is
+going to be `pending`. GitLab will create a downstream pipeline in the
+`my/deployment` project and as soon as the pipeline gets created, the `staging`
+job will succeed. `my/deployment` is a full path to that project.
 
-User that created the upstream pipeline needs to have access rights to the
+The user that created the upstream pipeline needs to have access rights to the
 downstream project (`my/deployment` in this case). If a downstream project can
 not be found, or a user does not have access rights to create pipeline there,
-`staging` job is going to be marked as _failed_.
+the `staging` job is going to be marked as _failed_.
 
-Note: `staging` job is going to succeed as soon as a downstream pipeline gets
-created. GitLab does not support status attribution yet, however adding
-first-class `trigger` configuration syntax is a ground work for implementing
+NOTE: **Note:**
+`staging` will succeed as soon as a downstream pipeline gets created.
+GitLab does not support status attribution yet, however adding first-class
+`trigger` configuration syntax is a ground work for implementing
 [status attribution](https://gitlab.com/gitlab-org/gitlab-ce/issues/39640).
 
-Note: Bridge jobs do not support every configuration entry that a user can use
-in case of regular jobs. Bridge jobs are not going to be picked by a runner,
+NOTE: **Note:**
+"Bridge" jobs do not support every configuration entry that a user can use
+in the case of regular jobs. "Bridge" jobs will not to be picked by a runner,
 thus there is no point in adding support for `script`, for example. If a user
-tries to used unsupported configuration syntax, YAML validation is going to
-fail upon pipeline creation.
+tries to used unsupported configuration syntax, YAML validation will fail upon
+pipeline creation.
 
-#### Specifying a downstream pipeline branch
+### Specifying a downstream pipeline branch
 
-It is possible to specify a branch name that a downstream pipeline is going to
-use.
+It is possible to specify a branch name that a downstream pipeline will use.
 
 ```yaml
 rspec:
@@ -111,14 +110,14 @@ staging:
 Use a `project` keyword to specify full path to a downstream project. Use
 `branch` keyword to specify a branch name.
 
-GitLab is going to use a commit that is currently on the HEAD of the branch
-when creating a downstream pipeline.
+GitLab will use a commit that is currently on the HEAD of the branch when
+creating a downstream pipeline.
 
-#### Passing variables to a downstream pipeline
+### Passing variables to a downstream pipeline
 
 Sometimes you might want to pass variables to a downstream pipeline.
-You can do that using `variables` keyword, just like you would do in case
-of defining a regular job.
+You can do that using the `variables` keyword, just like you would when
+defining a regular job.
 
 ```yaml
 rspec:
@@ -132,19 +131,18 @@ staging:
   trigger: my/deployment
 ```
 
-`ENVIRONMENT` variable is going to be passed to every job defined in a
-downstream pipeline. It is going to be available as an environment variable
-when GitLab Runner picks a job.
+The `ENVIRONMENT` variable will be passed to every job defined in a downstream
+pipeline. It will be available as an environment variable when GitLab Runner picks a job.
 
-#### Limitations
+### Limitations
 
-Because bridge jobs are a little different than regular jobs, it is not
+Because "bridge" jobs are a little different to regular jobs, it is not
 possible to use exactly the same configuration syntax here, as one would
-normally do when defining a regular job that is going to be picked by a runner.
+normally do when defining a regular job that will be picked by a runner.
 
-Some features, are not implemented yet, like support for environments.
+Some features are not implemented yet. For example, support for environments.
 
-Available configuration keywords are:
+[Configuration keywords](yaml/README.md) available for "bridge" jobs are:
 
 - `trigger` (to define a downstream pipeline trigger)
 - `stage`