addressing comments

Author: carlosrodlop

docs/BEST_PRACTICES.md

@@ -2,11 +2,11 @@
 This is a collection of tips, advice, gotchas and other best practices for using the [Jenkins Pipeline plugin](https://github.com/jenkinsci/workflow-plugin/blob/master/README.md). Contributions and comments are happily accepted.
 
 # General tips and advice
-* Do everything that makes sense there within `stage`s. This will make your builds easier to visualize, debug (e.g it isolates failures to a specific stage), display data (e.g it gets the execution time per build and per stage), etc.
+* Do everything that makes sense there within `stage`s. This will make your builds easier to visualize, debug, etc.
 * Do all real work that involves running a shell script, building, etc, within `node` blocks, so that it actually happens on a real executor, rather than a flyweight executor on the master node.
-* Get your flows from source control - `Jenkinsfile`s, loading libraries, global [CPS](https://en.wikipedia.org/wiki/Continuation-passing_style) library, you name it - but if you pull the main flow from SCM (i.e., Multibranch with `Jenkinsfile`s or `Pipeline from SCM`), be aware that you may need to whitelist a lot of method calls in the script security plugin. [JENKINS-28178](https://issues.jenkins-ci.org/browse/JENKINS-28178) has been created to simplify this, but you'll still want to be careful with that functionality due to the open security it implies. By getting your flows from source control, you benefit from `Jenkinsfile` versioning and also testing and merging against your CD Pipeline definition.
-* `input` shouldn’t be done within a `node` block - that eats up two executors waiting on the `input` feedback, both the flyweight executor that’s used for the `input` itself and the real executor used by the `node` block, which won’t free up until after the `input` itself has completed. When using `input` is recommendable to use `timeout` in order to avoid waiting for an infinite amount of time, and also control structures (`try/catch/finally`).
-* As Pipeline usage is adopted for more projects and more teams in an organization, common patterns should be stored in [Shared Libraries](https://jenkins.io/doc/book/pipeline/shared-libraries/).
+* Get your flows from source control - `Jenkinsfile`s, loading libraries, global [CPS](https://en.wikipedia.org/wiki/Continuation-passing_style) library, you name it - but if you pull the main flow from SCM (i.e., Multibranch with `Jenkinsfile`s or `Pipeline from SCM`), be aware that you may need to whitelist a lot of method calls in the script security plugin. By getting your flows from source control, you benefit from `Jenkinsfile` versioning and also testing and merging against your CD Pipeline definition.
+* `input` shouldn’t be done within a `node` block. When using `input` is recommendable to use `timeout` in order to avoid waiting for an infinite amount of time, and also control structures (`try/catch/finally`).
+* As Pipeline usage is adopted for more projects and more teams in an organization, common patterns should be stored in [Shared Libraries](https://jenkins.io/doc/book/pipeline/shared-libraries/). It is also an escape value for allowing out-of-sandbox execution in a safe context.
 * When coding functions, use unique names in your pipeline script and avoid using built-in/pre-defined items (such as "build", "stage", etc).  Using pre-defined methods may result in runtime issues, such as generating a `sandbox.RejectedAccessException` error when using build job DSL. 
 * Make use of the available [Pipeline Development Tools](https://jenkins.io/doc/book/pipeline/development/#pipeline-development-tools) for debugging your Pipeline as code.
 * Use [Multibranch Pipeline](https://jenkins.io/doc/book/pipeline/multibranch/) for project collaboration, new features (developed in separate branches) are validated before merging them to the master branch. Besides, it comes with automating features out-of-the-box (webhooks).