push/pull: roll back common problems, add troubleshooting guide

static/docs/command-reference/pull.md

@@ -100,19 +100,6 @@ reflinks or hardlinks to put it in the workspace without copying. See
 
 - `-v`, `--verbose` - displays detailed tracing information.
 
-## Common problems
-
-- `[Errno 24] Too many open files` - most common for MacOs users who work with
-  s3 remote. Each download thread needs to open one or more file descriptor(s).
-  The more `jobs` is specified, the more file descriptors needs to be open on
-  host filesystem. If there is too many open file descriptors, host filesystem
-  will not allow opening new ones. Recommended approach to handle this error is
-  to increase open file descriptors limit. On UNIX systems that can be done
-  using `ulimit -n`. In case of Windows, please refer to
-  [official resources](https://blogs.technet.microsoft.com/markrussinovich/2009/09/29/pushing-the-limits-of-windows-handles/).
-  If changing limits is impossible, the workaround would be to use lower `jobs`
-  option value.
-
 ## Examples
 
 For using the `dvc pull` command, a remote storage must be defined. (See

static/docs/command-reference/push.md

@@ -104,19 +104,6 @@ to push.
 
 - `-v`, `--verbose` - displays detailed tracing information.
 
-## Common problems
-
-- `[Errno 24] Too many open files` - most common for MacOs users who work with
-  s3 remote. Each upload thread needs to open one or more file descriptor(s).
-  The more `jobs` is specified, the more file descriptors needs to be open on
-  host filesystem. If there is too many open file descriptors, host filesystem
-  will not allow opening new ones. Recommended approach to handle this error is
-  to increase open file descriptors limit. On UNIX systems that can be done
-  using `ulimit -n`. In case of Windows, please refer to
-  [official resources](https://blogs.technet.microsoft.com/markrussinovich/2009/09/29/pushing-the-limits-of-windows-handles/).
-  If changing limits is impossible, the workaround would be to use lower `jobs`
-  option value.
-
 ## Examples
 
 For using the `dvc push` command, a remote storage must be defined. (See

static/docs/user-guide/troubleshooting.md

@@ -0,0 +1,17 @@
+# Troubleshooting
+
+In this section we cover some of the known issues that DVC user might stumbe
+upon.
+
+## Too many open files error
+
+A known problem some users run into with this command is
+`[Errno 24] Too many open files` (most common for S3 remotes on MacOS). The more
+`--jobs` specified, the more file descriptors need to be open on the host file
+system for each download thread, and the limit may be reached, causing this
+error.
+
+To solve this, it's often possible to increase the open file descriptors limit,
+for example with `ulimit -n` on UNIX-like system, or
+[increasing Handles limit](https://blogs.technet.microsoft.com/markrussinovich/2009/09/29/pushing-the-limits-of-windows-handles/)
+on Windows. Otherwise, please try using a lower `JOBS` value.