Merge pull request #490 from rtyler/pipeline-copy-edits

Address some of @scribblingfox's useful nits for the Pipeline chapter

STYLEGUIDE.adoc

@@ -30,6 +30,11 @@ ____
 As opposed to "the Jenkins cluster", "agent pool" or any other phrase to
 describe the collective set of resources provided by Jenkins.
 
+=== Conventional Terms/Phrases
+
+* We don't "reindex" we "re-index" (note the hypenation, see [this comment for
+  why](https://github.com/jenkins-infra/jenkins.io/pull/465#discussion_r90798432))
+
 == Syntax/Formatting
 
 Below are some tips for keeping documentation consistently formatted to ensure

content/doc/book/pipeline/getting-started.adoc

@@ -18,7 +18,7 @@ extensible set of tools for modeling simple-to-complex delivery pipelines "as
 code" via the Pipeline DSL.
 footnoteref:[dsl,link:https://en.wikipedia.org/wiki/Domain-specific_language[Domain-Specific Language]]
 
-This section will introduce some of the key concepts to Jenkins Pipeline and
+This section introduces some of the key concepts to Jenkins Pipeline and
 help introduce the basics of defining and working with Pipelines inside of a
 running Jenkins instance.
 
@@ -76,9 +76,9 @@ image::new-item-creation.png["Enter a name, select *Pipeline*, and click *OK*",
 
 
 
-* In the *Script* text-area, enter a Pipeline script and click *Save*.
+* In the *Script* text area, enter a Pipeline script and click *Save*.
 
-image::hello-world-script.png["In the *Script* text-area, enter a Pipeline script and click Save", role=center]
+image::hello-world-script.png["In the *Script* text area, enter a Pipeline script and click Save", role=center]
 
 * Click *Build Now* to run the Pipeline.
 
@@ -91,7 +91,7 @@ image::build-now.png["Click *Build Now* to run the Pipeline", role=center]
 image::hello-world-console-output.png["Click *Console Output* for the Pipeline", role=center]
 
 The example above shows a successful run of a basic Pipeline created in the Jenkins
-web UI, using two valuable steps.
+web UI, using two steps.
 
 [pipeline]
 ----
@@ -110,15 +110,13 @@ node { // <1>
 [[defining-a-pipeline-in-scm]]
 === Defining a Pipeline in SCM
 
-Complex pipelines would be cumbersome to write and maintain if you could only do
-that in the text area provided by the Jenkins job configuration page.
-
-Accordingly, you also have the option of writing Pipeline scripts
-(Jenkinsfiles) with a text editor and then loading those scripts into Jenkins
-using the *Pipeline Script from SCM* option.
+Complex pipelines are hard to write and maintain within the text area of the
+Pipeline configuration page. If necessary, you can write Pipeline scripts
+(Jenkinsfiles) in a text editor and access them in Jenkins with the *Pipeline
+Script from SCM* option.
 
 Loading pipeline scripts using the `checkout scm` step leverages the
-idea of "Pipeline as code" and allows easy maintenance of Pipelines with source
+idea of "Pipeline as Code" and allows easy maintenance of Pipelines with source
 control and text-editors.
 
 To do this, select *Pipeline script from SCM* when defining the pipeline.
@@ -166,7 +164,7 @@ on the plugins installed which explicitly expose steps for use in Pipeline.
 
 To generate a step snippet with the Snippet Generator:
 
-. Navigate to the Snippet Generator
+. Navigate to the *Pipeline Syntax* link (referenced above) from a configured Pipeline, or at link:http://localhost:8080/pipeline-syntax[localhost:8080/pipeline-syntax].
 . Select the desired step in the *Sample Step* dropdown menu
 . Use the dynamically populated area below the *Sample Step* dropdown to configure the selected step.
 . Click *Generate Pipeline Script* to create a snippet of Pipeline which can be
@@ -175,23 +173,23 @@ copied and pasted into a Pipeline.
 image::snippet-generator.png[Snippet Generator, role=center]
 
 To access additional information and/or documentation about the step selected,
-click on the help icon (blue question mark).
+click on the help icon (indicated by the red arrow in the image above).
 
 === Global Variable Reference
 
 In addition to the Snippet Generator, which only surfaces steps, Pipeline also
 provides a built-in "*Global Variable Reference*." Like the Snippet Generator,
 it is also dynamically populated by plugins. Unlike the Snippet Generator
 however, the Global Variable Reference only contains documentation for
-*variables*, provided by Pipeline or plugins, which are available for
+*variables* provided by Pipeline or plugins, which are available for
 Pipelines.
 
 The variables provided by default in Pipeline are:
 
 env::
 
 Environment variables accessible from Pipeline Script, for example:
-`env.PATH` or `env.BUILD_ID`. Consult the built-in 
+`env.PATH` or `env.BUILD_ID`. Consult the built-in
 link:http://localhost:8080/pipeline-syntax/globals#env[Global Variable Reference]
 for a complete, and up to date, list of environment variables
 available in Pipeline.

content/doc/book/pipeline/index.adoc

@@ -81,14 +81,14 @@ for aggregating test reports.
 
 Jenkins is, fundamentally, an automation engine which supports a number of
 automation patterns. Pipeline adds a powerful set of automation tools onto
-Jenkins, supporting use-cases that span from simple continuous integration to
+Jenkins, supporting use cases that span from simple continuous integration to
 comprehensive continuous delivery pipelines. By modeling a series of related
 tasks, users can take advantage of the many features of Pipeline:
 
-* *Code*: Pipelines are implemented "as code," and typically checked into
-  source control, giving teams the abilit to edit, review, and iterate upon
+* *Code*: Pipelines are implemented in code and typically checked into
+  source control, giving teams the ability to edit, review, and iterate upon
   their delivery pipeline.
-* *Durable*: Pipelines can survive both planned, and unplanned, restarts of the
+* *Durable*: Pipelines can survive both planned and unplanned restarts of the
   Jenkins master.
 * *Pausable*: Pipelines can optionally stop and wait for human input or approval
   before continuing the Pipeline run.
@@ -125,22 +125,21 @@ image::/images/pipeline/realworld-pipeline-flow.png[title="Pipeline Flow", 800]
 
 [[step]]
 Step::
-    A single task; fundamentally steps tell Jenkins _what_ to do. In
-    order to execute the shell command `make`, the `sh`
-    step would be used. For example `sh 'make'`.
+    A single task; fundamentally steps tell Jenkins _what_ to do. For example,
+    to execute the shell command `make` use the `sh` step: `sh 'make'`.
     When a plugin extends the Pipeline DSL, that typically means the plugin has
     implemented a new _step_.
 
 [[node]]
 Node::
-    Generally speaking, all _work_ which is done by a Pipeline, will be done in
-    the context of a single, or multiple, `node` step declarations, which does two things:
+    Most _work_ a Pipeline performs is done in the context of one or more
+    declared `node` steps. Confining the work inside of a node step does two
+    things:
     . Schedules the steps contained within the block to run by adding an item
       to the Jenkins queue. As soon as an executor is free on a node, the
       steps will run.
-    . Creates a workspace, a directory specific to that particular
-      Pipeline, where files can be checked out from source control and work can
-      be done.
+    . Creates a workspace (a directory specific to that particular
+      Pipeline) where work can be done on files checked out from source control.
 
 CAUTION: Depending on your Jenkins configuration, some workspaces may not get
 automatically cleaned up after a period of inactivity. See tickets and
@@ -151,7 +150,6 @@ for more information.
 [[stage]]
 Stage::
     `stage` is a step for defining a conceptually distinct subset of the
-    entire Pipeline, for example: "Build", "Test", and "Deploy". While stages
-    have no bearing on the execution of the Pipeline, they are used by many
+    entire Pipeline, for example: "Build", "Test", and "Deploy", which is tused by many.
     plugins to visualize or present Jenkins Pipeline status/progress.
     footnoteref:[blueocean,link:/projects/blueocean[Blue Ocean], link:https://wiki.jenkins-ci.org/display/JENKINS/Pipeline+Stage+View+Plugin[Pipeline Stage View plugin]]

content/doc/book/pipeline/multibranch.adoc

@@ -22,10 +22,9 @@ more dynamic and automatic functionality in Jenkins.
 The *Multibranch Pipeline* project type enables you to implement different
 Jenkinsfiles for different branches of the same project.
 In a Multibranch Pipeline project, Jenkins automatically discovers, manages and
-executes Pipelines for branches which contain a `Jenkinsfile` in source control
+executes Pipelines for branches which contain a `Jenkinsfile` in source control.
 
-This eliminates the need for manual Pipeline creation and management, as would
-be necessary when, for example, a developer adds a new feature branch.
+This eliminates the need for manual Pipeline creation and management.
 
 To create a Multibranch Pipeline:
 
@@ -57,12 +56,12 @@ Upon *Save*, Jenkins automatically scans the designated repository and creates
 appropriate items for each branch in the repository which contains a
 `Jenkinsfile`.
 
-By default, Jenkins will not automatically reindex the repository for branch
+By default, Jenkins will not automatically re-index the repository for branch
 additions or deletions (unless using an <<organization-folders,Organization Folder>>),
 so it is often useful to configure a Multibranch Pipeline to periodically
-reindex in the configuration:
+re-index in the configuration:
 
-image::multibranch-branch-indexing.png["Setting up branch reindexing", role=center]
+image::multibranch-branch-indexing.png["Setting up branch re-indexing", role=center]
 
 
 === Additional Environment Variables