From dc3cba7991d94d66cc3a8b111399045a2e7d02c2 Mon Sep 17 00:00:00 2001
From: Janice Niemeir <Janice.guerrero@gmail.com>
Date: Tue, 21 Aug 2018 17:18:28 -0700
Subject: [PATCH] Docs: Update parallel() documentation

---
 docs/api/parallel.md | 113 +++++++++++++++++++++++++++++++++++--------
 1 file changed, 93 insertions(+), 20 deletions(-)

diff --git a/docs/api/parallel.md b/docs/api/parallel.md
index 7d15efbbe..4229c8456 100644
--- a/docs/api/parallel.md
+++ b/docs/api/parallel.md
@@ -5,36 +5,109 @@ hide_title: true
 sidebar_label: parallel()
 -->
 
-# `gulp.parallel(...tasks)`
+# parallel()
 
-Takes a number of task names or functions and returns a function of the composed
-tasks or functions.
+Combines task functions and/or composed operations into larger operations that will be executed simultaneously. The composed operations from `series()` and `parallel()` can be nested to any depth.
 
-When using task names, the task should already be registered.
+## Usage
 
-When the returned function is executed, the tasks or functions will be executed
-in parallel, all being executed at the same time. If an error occurs,
-all execution will complete.
+```js
+const { parallel } = require('gulp');
+
+function javascript(cb) {
+  // body omitted
+  cb();
+}
+
+function css(cb) {
+  // body omitted
+  cb();
+}
+
+exports.build = parallel(javascript, css);
+```
+
+## Signature
 
 ```js
-gulp.task('one', function(done) {
-  // do stuff
-  done();
+parallel(...tasks)
+```
+
+### Parameters
+
+| parameter | type | note |
+|:--------------:|:------:|-------|
+| tasks <br> **(required)** | function <br> string | Any number of task functions can be passed as individual arguments. Strings can be used if you've registered tasks previously, but this is not recommended. |
+
+### Returns
+
+A composed operation to be registered as a task or nested within other `series` and/or `parallel` compositions.
+
+When the composed operation is executed, all tasks will be run at maximum concurrency. If an error occurs in one task, other tasks nondeterministically may or may not complete.
+
+### Errors
+
+When no tasks are passed, throws an error with the message, "One or more tasks should be combined using series or parallel".
+
+When invalid tasks or unregistered tasks are passed, throws an error with the message, "Task never defined".
+
+## Forward references
+
+A forward reference is when you compose tasks, using string references, that haven't been registered yet. This was a common practice in older versions, but this feature was removed to achieve faster task runtime and promote the use of named functions.
+
+In newer versions, you'll get an error, with the message "Task never defined", if you try to use forward references. You may experience this when trying to use `exports` for task registration _and_ composing tasks by string. In this situation, use named functions instead of string references.
+
+During migration, you may need the [forward reference registry][undertaker-forward-reference-external]. This will add an extra closure to every task reference and dramatically slow down your build. **Don't rely on this fix for very long**.
+
+## Avoid duplicating tasks
+
+When a composed operation is run, each task will be executed every time it was supplied.
+
+A `clean` task referenced in two different compositions would be run twice and lead to undesired results. Instead, refactor the `clean` task to be specified in the final composition.
+
+If you have code like this:
+```js
+// This is INCORRECT
+const { series, parallel } = require('gulp');
+
+const clean = function(cb) {
+  // body omitted
+  cb();
+};
+
+const css = series(clean, function(cb) {
+  // body omitted
+  cb();
 });
 
-gulp.task('two', function(done) {
-  // do stuff
-  done();
+const javascript = series(clean, function(cb) {
+  // body omitted
+  cb();
 });
 
-gulp.task('default', gulp.parallel('one', 'two', function(done) {
-  // do more stuff
-  done();
-}));
+exports.build = parallel(css, javascript);
 ```
 
-## tasks
-Type: `Array`, `String` or `Function`
+Migrate to this:
+```js
+const { series, parallel } = require('gulp');
+
+function clean(cb) {
+  // body omitted
+  cb();
+}
 
-A task name, a function or an array of either.
+function css(cb) {
+  // body omitted
+  cb();
+}
+
+function javascript(cb) {
+  // body omitted
+  cb();
+}
+
+exports.build = series(clean, parallel(css, javascript));
+```
 
+[undertaker-forward-reference-external]: https://github.com/gulpjs/undertaker-forward-reference