document parallel

Author: davidjgoss

docs/cli.md

@@ -122,21 +122,7 @@ Note that the rerun file parser can only work with the default separator for now
 
 ## Parallel
 
-You can run your scenarios in parallel with `--parallel <NUMBER_OF_WORKERS>`. Each worker is run in a separate Node process and receives the following env variables (as well as a copy of `process.env` from the coordinator process):
-
-* `CUCUMBER_PARALLEL` - set to 'true'
-* `CUCUMBER_TOTAL_WORKERS` - set to the number of workers
-* `CUCUMBER_WORKER_ID` - ID for worker ('0', '1', '2', etc.)
-
-### Timing
-
-When using parallel mode, the last line of the summary output differentiates between real time elapsed during the test run and aggregate time spent actually running steps: 
-
-```
-73 scenarios (73 passed)
-512 steps (512 passed)
-0m51.627s (executing steps: 4m51.228s)
-```
+See [Parallel](./parallel.md).
 
 ## Profiles
 

docs/parallel.md

@@ -0,0 +1,29 @@
+# Parallel
+
+Cucumber supports running scenarios in parallel. The main process becomes a "coordinator" and spins up several separate Node processes to be the "workers". You can enable this with the `--parallel <NUMBER_OF_WORKERS>` CLI option:
+
+```shell
+$ cucumber-js --parallel 3
+```
+
+The number you provide is the number of workers that will run scenarios in parallel.
+
+Each worker receives the following env variables (as well as a copy of `process.env` from the coordinator process):
+
+* `CUCUMBER_PARALLEL` - set to 'true'
+* `CUCUMBER_TOTAL_WORKERS` - set to the number of workers
+* `CUCUMBER_WORKER_ID` - ID for worker ('0', '1', '2', etc.)
+
+### Timing
+
+When using parallel mode, the last line of the summary output differentiates between real time elapsed during the test run and aggregate time spent actually running steps:
+
+```
+73 scenarios (73 passed)
+512 steps (512 passed)
+0m51.627s (executing steps: 4m51.228s)
+```
+
+### Hooks
+
+When using parallel mode, any `BeforeAll` and `AfterAll` hooks you have defined will run _once per worker_.

docs/profiles.md

@@ -37,5 +37,5 @@ $ cucumber-js --profile ci
 
 Some notes about how Profiles work:
 
-- The `--profile` CLI option is repeatable, so you can apply multiple profiles at once
-- You can still supply options directly on the command line when using profiles, they will be appended to whatever comes from profiles
+- The `--profile` CLI option is repeatable, so you can apply multiple profiles at once.
+- You can still supply options directly on the command line when using profiles, they will be appended to whatever comes from profiles.

docs/retry.md

@@ -1,6 +1,6 @@
 # Retry
 
-If you have a flaky scenario (e.g. failing 10% of the time for some reason), you can use *Retry* to have Cucumber attempt it multiple times until either it passes or the maximum number of attempts is reached. You enable this via the `--retry` CLI option, like this:
+If you have a flaky scenario (e.g. failing 10% of the time for some reason), you can use *Retry* to have Cucumber attempt it multiple times until either it passes or the maximum number of attempts is reached. You enable this via the `--retry <MAXIMUM_RETRIES>` CLI option, like this:
 
 ```shell
 $ cucumber-js --retry 1
@@ -19,7 +19,7 @@ Some notes on how Retry works:
 
 ## Targeting scenarios
 
-Using the `--retry` option alone would mean every scenario would be allowed multiple attempts - this almost certainly isn't what you want, assuming you have a small set of flaky scenarios. To target just the relevant scenarios, you can provide a [tag expression](https://cucumber.io/docs/cucumber/api/#tag-expressions) via the `--retry-tag-filter` CLI option, like this:
+Using the `--retry` option alone would mean every scenario would be allowed multiple attempts - this almost certainly isn't what you want, assuming you have a small set of flaky scenarios. To target just the relevant scenarios, you can provide a [tag expression](https://cucumber.io/docs/cucumber/api/#tag-expressions) via the `--retry-tag-filter <TAG_EXPRESSION>` CLI option, like this:
 
 ```shell
 $ cucumber-js --retry 1 --retry-tag-filter @flaky