Docs: API documentation improvements based on feedback

Author: phated

docs/api/concepts.md

@@ -54,7 +54,9 @@ File system modes determine what permissions exist for a file. Most files and di
 
 ## Modules
 
-Gulp is made up of many small modules that are pulled together to work cohesively. By utilizing [semver][semver-external] within the small modules, we can release bug fixes and features without publishing new versions of gulp. If you encounter an issue related to one of these modules, open an issue on the individual project repository.
+Gulp is made up of many small modules that are pulled together to work cohesively. By utilizing [semver][semver-external] within the small modules, we can release bug fixes and features without publishing new versions of gulp. Often, when you don't see progress on the main repository, work is being done in one of these modules.
+
+If you're having trouble, ensure your current modules are updated - using the `npm update` command. If the problem persists, open an issue on the individual project repository.
 
 * [undertaker][undertaker-external] - the task registration system
 * [vinyl][vinyl-external] - the virtual file objects

docs/api/parallel.md

@@ -7,7 +7,7 @@ sidebar_label: parallel()
 
 # parallel()
 
-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.
+Combines task functions and/or composed operations into larger operations that will be executed simultaneously. There are no imposed limits on the nesting depth of composed operations using `series()` and `parallel()`.
 
 ## Usage
 

docs/api/series.md

@@ -7,7 +7,7 @@ sidebar_label: series()
 
 # series()
 
-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.
+Combines task functions and/or composed operations into larger operations that will be executed one after another, in sequential order. There are no imposed limits on the nesting depth of composed operations using `series()` and `parallel()`.
 
 ## Usage
 

docs/api/src.md

@@ -9,7 +9,7 @@ sidebar_label: src()
 
 Creates a stream for reading [Vinyl][vinyl-concepts] objects from the file system.
 
-**Note:** Any UTF-8 BOMs will be removed from UTF-8 files read by `src()`, unless disabled using the `removeBOM` option.
+**Note:** BOMs (byte order marks) have no purpose in UTF-8 and will be removed from UTF-8 files read by `src()`, unless disabled using the `removeBOM` option.
 
 ## Usage
 
@@ -58,7 +58,7 @@ When an invalid glob is given in `globs`, throws an error with the message, "Inv
 | buffer | boolean <br> function | true | When true, file contents are buffered into memory. If false, the Vinyl object's `contents` property will be a paused stream. Contents of large files may not be able to be buffered. <br> **Note:** Plugins may not implement support for streaming contents. |
 | read | boolean <br> function | true | If false, files will be not be read and their Vinyl objects won't be writable to disk via `.dest()`. |
 | since | date <br> timestamp <br> function | | When set, only creates Vinyl objects for files that have been modified since the specified time. |
-| removeBOM | boolean <br> function | true | When true, removes the BOM from UTF-8 encoded files. If false, ignores a BOM.. |
+| removeBOM | boolean <br> function | true | When true, removes the BOM from UTF-8 encoded files. If false, ignores a BOM. |
 | sourcemaps | boolean <br> function | false | If true, enables [sourcemaps][sourcemaps-section] support on Vinyl objects created. Loads inline sourcemaps and resolves external sourcemap links. |
 | resolveSymlinks | boolean <br> function | true | When true, recursively resolves symbolic links to their targets. If false, preserves the symbolic links and sets the Vinyl object's `symlink` property to the original file's path. |
 | cwd | string | `process.cwd()` | The directory that will be combined with any relative path to form an absolute path. Is ignored for absolute paths. Use to avoid combining `globs` with `path.join()`. <br> _This option is passed directly to [glob-stream][glob-stream-external]._ |

docs/api/symlink.md

@@ -10,7 +10,7 @@ sidebar_label: symlink()
 Creates a stream for linking [Vinyl][vinyl-concepts] objects to the file system.
 
 ## Usage
-'
+
 ```js
 const { src, symlink } = require('gulp');
 

docs/api/task.md

@@ -7,7 +7,7 @@ sidebar_label: task()
 
 # task()
 
-**Reminder**: This API isn't the recommended pattern anymore - export your tasks.
+**Reminder**: This API isn't the recommended pattern anymore - [export your tasks][creating-tasks-docs].
 
 Defines a task within the task system. The task can then be accessed from the command line and the `series()`, `parallel()`, and `lastRun()` APIs.
 
@@ -106,4 +106,5 @@ task(build);
 
 [task-metadata-section]: #task-metadata
 [task-concepts]: concepts.md#tasks
+[creating-tasks-docs]: ../getting-started/3-creating-tasks.md
 [function-name-external]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/name

docs/api/vinyl.md

@@ -120,7 +120,7 @@ All internally managed paths - any instance property except `contents` and `stat
 
 ## Normalization and concatenation
 
-All path properties are normalized by their setters. Concatenate paths with `/`, instead of using `path.join()`, and normalization will occur properly on all platforms. Never concatenate with `\` - it  is a valid filename character on posix system.
+All path properties are normalized by their setters. Concatenate paths with `/`, instead of using `path.join()`, and normalization will occur properly on all platforms. Never concatenate with `\` - it  is a valid filename character on POSIX system.
 
 ```js
 const file = new File();