Docs: Improve & fix parts of Getting Started

gulpjs · Jul 29, 2018 · 84b0234 · 84b0234
1 parent 9f4a2e9
commit 84b0234
Show file tree

Hide file tree

Showing 6 changed files with 59 additions and 30 deletions.
diff --git a/docs/getting-started/1-quick-start.md b/docs/getting-started/1-quick-start.md
@@ -52,17 +52,21 @@ npm install --save-dev gulp
 ```
 
 ### Verify your gulp versions
+
 ```sh
 gulp --version
 ```
+
+Ensure the output matches the screenshot below or you might need to restart the steps in this guide.
+
 ![Output: CLI version 2.0.1 & Local version 4.0.0][img-gulp-version-command]
 
 ### Create a gulpfile
 Using your text editor, create a file named gulpfile.js in your project root with these contents:
 ```js
-function defaultTask(done) {
+function defaultTask(cb) {
   // place code for your default task here
-  done();
+  cb();
 }
 
 exports.default = defaultTask

diff --git a/docs/getting-started/3-creating-tasks.md b/docs/getting-started/3-creating-tasks.md
@@ -160,17 +160,18 @@ exports.build = series(
 );
 ```
 
-When a composed operation is run, each task will be executed every time it was referenced.  For example, a `clean` task referenced before two different tasks would be run twice and lead to undesired results.  Tasks can be wrapped with the [async-once][async-once] module if this **(not recommended)** pattern is needed.
+When a composed operation is run, each task will be executed every time it was referenced.  For example, a `clean` task referenced before two different tasks 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 pattern is NOT recommended but some edge cases might require it.
-const { series } = require('gulp');
-const once = require('async-once');
+// This is INCORRECT
+const { series, parallel } = require('gulp');
 
-const clean = once(function(cb) {
+const clean = function(cb) {
   // body omitted
   cb();
-});
+};
 
 const css = series(clean, function(cb) {
   // body omitted
@@ -180,9 +181,32 @@ const css = series(clean, function(cb) {
 const javascript = series(clean, function(cb) {
   // body omitted
   cb();
-})
+});
+
+exports.build = parallel(css, javascript);
+```
+
+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(css, javascript);
+exports.build = series(clean, parallel(css, javascript));
 ```
 
 [async-completion-docs]: 4-async-completion.md

diff --git a/docs/getting-started/4-async-completion.md b/docs/getting-started/4-async-completion.md
@@ -32,7 +32,7 @@ exports.default = streamTask;
 
 ```js
 function promiseTask() {
-  return Promise.resolve('some ignored value');
+  return Promise.resolve('the value is ignored');
 }
 
 exports.default = promiseTask;
@@ -79,12 +79,12 @@ exports.default = observableTask;
 
 ### Using an error-first callback
 
-If nothing is returned from your task, you must use the error-first callback to signal completion. The callback will be passed to your task as the only argument - named `done()` in the examples below.
+If nothing is returned from your task, you must use the error-first callback to signal completion. The callback will be passed to your task as the only argument - named `cb()` in the examples below.
 
 ```js
-function callbackTask(done) {
-  // `done()` should be called by some async work
-  done();
+function callbackTask(cb) {
+  // `cb()` should be called by some async work
+  cb();
 }
 
 exports.default = callbackTask;
@@ -93,9 +93,9 @@ exports.default = callbackTask;
 To indicate to gulp that an error occurred in a task using an error-first callback, call it with an `Error` as the only argument.
 
 ```js
-function callbackError(done) {
-  // `done()` should be called by some async work
-  done(new Error('kaboom'));
+function callbackError(cb) {
+  // `cb()` should be called by some async work
+  cb(new Error('kaboom'));
 }
 
 exports.default = callbackError;
@@ -106,8 +106,8 @@ However, you'll often pass this callback to another API instead of calling it yo
 ```js
 const fs = require('fs');
 
-function passingCallback(done) {
-  fs.access('gulpfile.js', done);
+function passingCallback(cb) {
+  fs.access('gulpfile.js', cb);
 }
 
 exports.default = passingCallback;

diff --git a/docs/getting-started/5-working-with-files.md b/docs/getting-started/5-working-with-files.md
@@ -35,7 +35,7 @@ exports.default = function() {
 }
 ```
 
-`dest()`  is given an output directory string which is generally used as a terminator stream. When it receives a file passed through the pipeline, it writes the contents and other details out to the filesystem at a given directory.  The `symlink()` method is also available and operates like `dest()`, but creates links instead of files (see [`symlink()`][symlink-api-docs] for details).
+`dest()` is given an output directory string and also produces a [Node stream][node-streams-docs] which is generally used as a terminator stream. When it receives a file passed through the pipeline, it writes the contents and other details out to the filesystem at a given directory.  The `symlink()` method is also available and operates like `dest()`, but creates links instead of files (see [`symlink()`][symlink-api-docs] for details).
 
 Most often plugins will be placed between `src()` and `dest()` using the `.pipe()` method and will transform the files within the stream.
 
@@ -61,9 +61,9 @@ exports.default = function() {
 
 ## Output in phases
 
-`dest()` can be used in the middle of a pipeline to write intermediate states to the filesystem. When a file is received, the current state is written out to the filesystem, the path is updated to represent the new location of the output file, then that file is passed down the pipeline.
+`dest()` can be used in the middle of a pipeline to write intermediate states to the filesystem. When a file is received, the current state is written out to the filesystem, the path is updated to represent the new location of the output file, then that file continues down the pipeline.
 
-This feature can be useful to create an unminified and minified file with the same pipeline.
+This feature can be useful to create unminified and minified files with the same pipeline.
 
 ```js
 const { src, dest } = require('gulp');

diff --git a/docs/getting-started/7-using-plugins.md b/docs/getting-started/7-using-plugins.md
@@ -103,6 +103,7 @@ exports.default = function() {
         const code = uglify.minify(file.contents.toString())
         file.contents = Buffer.from(code)
       }
+      cb(null, file);
     }))
     .pipe(dest('output/'));
 }

diff --git a/docs/getting-started/8-watching-files.md b/docs/getting-started/8-watching-files.md
@@ -15,17 +15,17 @@ This API provides built-in delay and queueing based on most-common-use defaults.
 const { watch, series } = require('gulp');
 
 function clean(cb) {
-  // Body omitted
+  // body omitted
   cb();
 }
 
 function javascript(cb) {
-  // Body omitted
+  // body omitted
   cb();
 }
 
 function css(cb) {
-  // Body omitted
+  // body omitted
   cb();
 }
 
@@ -51,7 +51,7 @@ const { watch } = require('gulp');
 
 // All events will be watched
 watch('src/*.js', { events: 'all' }, function(cb) {
-  // Body omitted
+  // body omitted
   cb();
 });
 ```
@@ -67,7 +67,7 @@ const { watch } = require('gulp');
 
 // The task will be executed upon startup
 watch('src/*.js', { ignoreInitial: false }, function(cb) {
-  // Body omitted
+  // body omitted
   cb();
 });
 ```
@@ -83,7 +83,7 @@ const { watch } = require('gulp');
 
 // The task will be run (concurrently) for every change made
 watch('src/*.js', { queue: false }, function(cb) {
-  // Body omitted
+  // body omitted
   cb();
 });
 ```
@@ -99,7 +99,7 @@ const { watch } = require('gulp');
 
 // The task won't be run until 500ms have elapsed since the first change
 watch('src/*.js', { delay: 500 }, function(cb) {
-  // Body omitted
+  // body omitted
   cb();
 });
 ```