From 4169cb6de2d1bab681aed6f38c00e441bb80578a Mon Sep 17 00:00:00 2001
From: Janice Niemeir <Janice.guerrero@gmail.com>
Date: Tue, 21 Aug 2018 17:19:31 -0700
Subject: [PATCH] Docs: Update series() documentation

---
 docs/api/series.md | 114 +++++++++++++++++++++++++++++++++++++--------
 1 file changed, 94 insertions(+), 20 deletions(-)

diff --git a/docs/api/series.md b/docs/api/series.md
index 9499ed42f..fd2c4987a 100644
--- a/docs/api/series.md
+++ b/docs/api/series.md
@@ -5,35 +5,109 @@ hide_title: true
 sidebar_label: series()
 -->
 
-# `gulp.series(...tasks)`
+# series()
 
-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 one after another, in sequential order. 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 series, each waiting for the prior to finish. If an error occurs,
-execution will stop.
+```js
+const { series } = require('gulp');
+
+function javascript(cb) {
+  // body omitted
+  cb();
+}
+
+function css(cb) {
+  // body omitted
+  cb();
+}
+
+exports.build = series(javascript, css);
+```
+
+## Signature
+
+```js
+series(...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 sequentially. If an error occurs in one task, no subsequent tasks will be run.
+
+### 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 your task registration *and* composing tasks by string. In this situation, use named functions instead of string references.
+
+During migration, you may need to use 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
-gulp.task('one', function(done) {
-  // do stuff
-  done();
+// 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.series('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();
+}
+
+function css(cb) {
+  // body omitted
+  cb();
+}
+
+function javascript(cb) {
+  // body omitted
+  cb();
+}
+
+exports.build = series(clean, parallel(css, javascript));
+```
 
-A task name, a function or an array of either.
+[undertaker-forward-reference-external]: https://github.com/gulpjs/undertaker-forward-reference