treeverse · jorgeorpinel · Mar 26, 2020 · Mar 19, 2020 · Mar 19, 2020 · Mar 19, 2020
diff --git a/content/docs/command-reference/gc.md b/content/docs/command-reference/gc.md
@@ -22,11 +22,11 @@ files if no scope options are provided. It means it's user's responsibility to
 explicitly provide the right set of options to specify what data is still needed
 (so that DVC can figure out what fils can be safely deleted).
 
-One of the scope options, `--workspace`, `--all-branches`, `--all-tags`,
-`--all-commits`, or any combination of them must be provided. Each of them
-corresponds to the current workspace _and_ a set of commits to analyze what
-files, directories and what versions are still needed and should be kept (by
-analyzing DVC-files in those commits).
+One of the scope options (`--workspace`, `--all-branches`, `--all-tags`,
+`--all-commits`) or a combination of them must be provided. Each of them
+corresponds to keeping the data for the current workspace, and for a certain set
+of commits (determined by reading the DVC-files in them). See the
+[Options](#options) section for more details.
 
 Unless the `--cloud` option is used, `dvc gc` does not remove data files from
 any remote. This means that any files collected from the local cache can be
@@ -61,10 +61,11 @@ The default remote is cleaned (see `dvc config core.remote`) unless the
   commits as well as the workspace (implies `-w`). Useful for keeping all the
   data used in the entire existing commit history of the project.
 
-  One of the use cases for this option is to safely delete all temporary data
-  DVC cached when `dvc run` and/or `dvc repro` were run without committing
-  changes to DVC-files (thus potentially caching data that is not referenced
-  from workspace or Git commits).
+  A use case for this option is to safely delete all temporary data `dvc run`
+  and/or `dvc repro` cache when used without committing changes (see the `-O` or
+  `-M`, and `--no-commit` options in those commands). In that scenario, data
+  that is never referenced from the workspace or from any Git commit can still
+  be stored in the project's cache).
 
 - `-p <paths>`, `--projects <paths>` - if a single remote or a single cache is
   shared among different projects (e.g. a configuration like the one described

diff --git a/content/docs/command-reference/install.md b/content/docs/command-reference/install.md
@@ -75,11 +75,11 @@ directory:
 To disable them, you need to **remove** or **edit** those files (i.e.
 `rm .git/hooks/post-checkout`, `vim .git/hooks/pre-commit`).
 
-## Using Pre-Commit tool
+## Using the Pre-commit tool
 
-DVC provides support for [pre-commit](https://pre-commit.com/) users. To adjust
-`.pre-commit-config.yaml` you could either use
-`dvc install --use-pre-commit-tool`, or add these entries by hand:
+DVC provides support to manage Git hooks with
+[pre-commit](https://pre-commit.com/). To adjust `.pre-commit-config.yaml`, you
+can either use `dvc install --use-pre-commit-tool` or add these entries by hand:
 
 ```yaml
 repos:
@@ -103,8 +103,9 @@ repos:
 
 ## Options
 
-- `--use-pre-commit-tool` - install pre-commit/pre-push/post-checkout hooks into
-  the [pre-commit](https://pre-commit.com/) config (`.pre-commit-config.yaml`).
+- `--use-pre-commit-tool` - installs pre-commit, pre-push, post-checkout Git
+  hooks into the [pre-commit](https://pre-commit.com/) config file
+  (`.pre-commit-config.yaml`).
 
 - `-h`, `--help` - prints the usage/help message, and exit.
 

diff --git a/content/docs/command-reference/metrics/add.md b/content/docs/command-reference/metrics/add.md
@@ -1,7 +1,6 @@
 # metrics add
 
-Mark <abbr>output</abbr> file as a
-[project metric](/doc/command-reference/metrics).
+Mark a DVC-tracked file as a [project metric](/doc/command-reference/metrics).
 
 ## Synopsis
 

diff --git a/content/docs/command-reference/metrics/remove.md b/content/docs/command-reference/metrics/remove.md
@@ -1,8 +1,8 @@
 # metrics remove
 
-Stop tracking a [project metric](/doc/command-reference/metrics): Keeps file
-located at `path` as an <abbr>output</abbr>, but removes its metric mark in the
-DVC-file.
+Remove metric mark on a DVC-tracked file: Keeps file located at `path` as an
+<abbr>output</abbr>, but removes its mark as a
+[project metric](/doc/command-reference/metrics) in the DVC-file.
 
 ## Synopsis
 

diff --git a/content/docs/command-reference/remove.md b/content/docs/command-reference/remove.md
@@ -1,6 +1,6 @@
 # remove
 
-Remove data files or directories tracked by DVC.
+Remove DVC-tracked files or directories from the <abbr>workspace</abbr>.
 
 ## Synopsis
 

diff --git a/content/docs/command-reference/root.md b/content/docs/command-reference/root.md
@@ -1,6 +1,6 @@
 # root
 
-Return the relative path to the <abbr>DVC project</abbr>.
+Return the relative path to the root of the <abbr>DVC project</abbr>.
 
 ## Synopsis
 
@@ -11,9 +11,10 @@ usage: dvc root [-h] [-q | -v]
 ## Description
 
 While in sub-directories of the project, sometimes developers may want to refer
-some file belonging to another directory. This command returns relative path to
-the project root from the current working directory. So this command can be used
-to build a path to a dependency file, command, or output.
+some file belonging to another directory. This command returns the path to the
+root directory of the current <abbr>DVC project</abbr>, relative to the current
+working directory. This command can be used to build a path to a dependency
+file, command, or output.
 
 ## Options
 

diff --git a/content/docs/install/linux.md b/content/docs/install/linux.md
@@ -29,7 +29,7 @@ plan to use, you might need to install optional dependencies: `[s3]`, `[azure]`,
 ### Example: How to install DVC with support for Amazon S3 storage
 
 ```dvc
-$ pip install 'dvc[s3]'
+$ pip install "dvc[s3]"
 ```
 
 In this case it installs `boto3` library as well, besides DVC.

diff --git a/content/docs/install/macos.md b/content/docs/install/macos.md
@@ -47,7 +47,7 @@ plan to use, you might need to install optional dependencies: `[s3]`, `[azure]`,
 ### Example: How to install DVC with support for Amazon S3 storage
 
 ```dvc
-$ pip install 'dvc[s3]'
+$ pip install "dvc[s3]"
 ```
 
 In this case it installs `boto3` library as well, besides DVC.

diff --git a/content/docs/install/windows.md b/content/docs/install/windows.md
@@ -26,7 +26,7 @@ on GitHub.
 
 You can use `conda` from
 [Anaconda Prompt](https://docs.anaconda.com/anaconda/user-guide/getting-started/#open-prompt-win),
-which is a POSIX-like command line terminal in Windows.
+a POSIX-like command line terminal in Windows.
 
 ```dvc
 $ conda install -c conda-forge dvc
@@ -36,9 +36,8 @@ $ conda install -c conda-forge dvc
 
 ## Install with pip
 
-You can install with `pip` from a command line terminal like
-[Git Bash](https://gitforwindows.org/#bash) or
-[WSL](https://blogs.windows.com/windowsdeveloper/2016/03/30/run-bash-on-ubuntu-on-windows/).
+From Command Prompt or other
+[recommended consoles](/doc/user-guide/running-dvc-on-windows):
 
 ```dvc
 $ pip install dvc
@@ -53,7 +52,7 @@ plan to use, you might need to install optional dependencies: `[s3]`, `[azure]`,
 ### Example: How to install DVC with support for Amazon S3 storage
 
 ```dvc
-$ pip install 'dvc[s3]'
+$ pip install "dvc[s3]"
 ```
 
 In this case it installs `boto3` library as well, besides DVC.

diff --git a/content/docs/user-guide/contributing/docs.md b/content/docs/user-guide/contributing/docs.md
@@ -62,8 +62,8 @@ $ git clone git@github.com:<username>/dvc.org.git
 $ cd dvc.org
 ```
 
-Make sure you have the latest version of [Node.js](https://nodejs.org/en/), and
-install [Yarn](https://yarnpkg.com/):
+Make sure you have a recent version of [Node.js](https://nodejs.org/en/)
+(`^12.0.0`), and install [Yarn](https://yarnpkg.com/):
 
 ```dvc
 $ npm install -g yarn
@@ -118,7 +118,7 @@ The first few of the rules below should be enforced automatically by a Git
 pre-commit hook that is integrated when `yarn` installs the project dependencies
 (explained above).
 
-- No trailing whitespaces are allowed.
+- No trailing white spaces are allowed.
 
 - Content must be properly formatted at 80 symbols width.
 

diff --git a/content/docs/user-guide/running-dvc-on-windows.md b/content/docs/user-guide/running-dvc-on-windows.md
@@ -5,22 +5,28 @@ involving system performance. Some, for example, have to do with NTFS file
 system characteristics and Windows built-in security mechanisms. Below are some
 workarounds that can help avoid these potential problems:
 
-## POSIX-like command line shell
-
-Many of the DVC commands have POSIX-style options that are given with a double
-dash `--`. This isn't supported by the simple Windows command prompt `cmd`.
-
-Common Windows terminal alternatives are
-[Git Bash](https://gitforwindows.org/#bash) or
-[Anaconda Prompt](https://docs.anaconda.com/anaconda/user-guide/getting-started/#open-prompt-win)
-– but they may not support all the POSIX features (e.g. `\` line continuation).
-
-💡 We recommend the full [Cmder](https://cmder.net/) console emulator (which
-already includes _Git for Windows_).
-
-Its also possible to enjoy a full Linux terminal experience with the
-[WSL](https://blogs.windows.com/windowsdeveloper/2016/03/30/run-bash-on-ubuntu-on-windows/)
-– but it may not be possible to access GPUs from this subsystem.
+## POSIX-like command line experience
+
+The regular Command Prompt (`cmd`) in Windows will most likely not help you use
+DVC effectively, or follow the examples in our docs. Please avoid it. There's no
+perfect solution, bu here are some ideas:
+
+- The full [Cmder](https://cmder.net/) console emulator combines several useful
+  tools like [ConEmu](https://conemu.github.io/), and
+  [Git for Windows](https://gitforwindows.org/)\* (Git Bash) among other
+  [shell options](https://github.com/cmderdev/cmder/blob/master/README.md#access-to-multiple-shells-in-one-window-using-tabs).
+- [Anaconda Prompt](https://docs.anaconda.com/anaconda/user-guide/getting-started/#open-prompt-win)
+  is another recommendation, but it may not support all the desired CLI features
+  (e.g. `\` line continuation).
+- Consider enabling and using
+  [WSL](https://blogs.windows.com/windowsdeveloper/2016/03/30/run-bash-on-ubuntu-on-windows/)
+  ([Windows Terminal](https://devblogs.microsoft.com/commandline/) also
+  recommended). But it has major
+  [I/O performance issues](https://www.phoronix.com/scan.php?page=article&item=windows10-okt-wsl&num=2)
+  and is [unable to access GPUs](https://github.com/Microsoft/WSL/issues/829),
+  et al.\*
+- Install an actual Linux distro (e.g. Ubuntu) on a virtual machine, or in a HD
+  partition (dual boot).
 
 ## Disable short-file name generation
 
@@ -65,6 +71,6 @@ via [Chocolatey](https://chocolatey.org/) (please install the tool first):
 $ choco install less
 ```
 
-`less` can be installed in other ways, just make sure it's available in
-`cmd`/PowerShell, where you run `dvc`. (This usually means adding the directory
-where `less` is installed to the `PATH` environment variable.)
+`less` can be installed in other ways, just make sure it's available in the
+command line environment where you run `dvc`. (This usually means adding the
+directory where `less` is installed to the `PATH` environment variable.)