treeverse · jorgeorpinel · Mar 12, 2020 · Feb 22, 2020 · Feb 24, 2020 · Feb 24, 2020
diff --git a/public/static/docs/command-reference/cache/index.md b/public/static/docs/command-reference/cache/index.md
@@ -15,9 +15,10 @@ positional arguments:
 
 ## Description
 
-After DVC initialization, a hidden directory `.dvc/` is created to contain the
-[DVC files and directories](/doc/user-guide/dvc-files-and-directories),
-including the default cache directory.
+At DVC initialization, a new `.dvc/` directory will be created for internal
+configuration and cache
+[files and directories](/doc/user-guide/dvc-files-and-directories) that are
+hidden from the user.
 
 The cache is where your data files, models, etc (anything you want to version
 with DVC) are actually stored. The corresponding files you see in the

diff --git a/public/static/docs/command-reference/fetch.md b/public/static/docs/command-reference/fetch.md
@@ -1,6 +1,6 @@
 # fetch
 
-Get files or directories tracked by DVC from
+Get tracked files or directories from
 [remote storage](/doc/command-reference/remote) into the <abbr>cache</abbr>.
 
 ## Synopsis
@@ -17,12 +17,11 @@ positional arguments:
 
 ## Description
 
-The `dvc fetch` command is a means to download files from remote storage into
-the cache of the project, but without placing them in the
-<abbr>workspace</abbr>. This makes the data files available for linking (or
-copying) into the workspace. (Refer to
-[dvc config cache.type](/doc/command-reference/config#cache).) Along with
-`dvc checkout`, it's performed automatically by `dvc pull` when the target
+The `dvc fetch` downloads DVC-tracked files from remote storage into the cache
+of the project, but without placing them in the <abbr>workspace</abbr>. This
+makes the data files available for linking (or copying) into the workspace.
+(Refer to [dvc config cache.type](/doc/command-reference/config#cache).) Along
+with `dvc checkout`, it's performed automatically by `dvc pull` when the target
 [DVC-files](/doc/user-guide/dvc-file-format) are not already in the cache:
 
 ```
@@ -44,10 +43,10 @@ project's cache                  ++ | dvc pull |
 
 Fetching could be useful when first checking out a <abbr>DVC project</abbr>,
 since files tracked by DVC should already exist in remote storage, but won't be
-in the project's cache. (Refer to `dvc remote` for more information on DVC
-remotes.) These necessary data or model files are listed as dependencies or
-outputs in a DVC-file (target [stage](/doc/command-reference/run)) so they are
-required to [reproduce](/doc/get-started/reproduce) the corresponding
+in the project's <abbr>cache</abbr>. (Refer to `dvc remote` for more information
+on DVC remotes.) These necessary data or model files are listed as dependencies
+or outputs in a DVC-file (target [stage](/doc/command-reference/run)) so they
+are required to [reproduce](/doc/get-started/reproduce) the corresponding
 [pipeline](/doc/command-reference/pipeline). (See
 [DVC-File Format](/doc/user-guide/dvc-file-format) for more information on
 dependencies and outputs.)

diff --git a/public/static/docs/command-reference/get.md b/public/static/docs/command-reference/get.md
@@ -11,8 +11,8 @@ directory.
 usage: dvc get [-h] [-q | -v] [-o [OUT]] [--rev [REV]] url path
 
 positional arguments:
-  url              Location of DVC or Git repository to download from.
-  path             Path to a file or directory within the repository.
+  url              Location of DVC or Git repository to download from
+  path             Path to a file or directory within the repository
 ```
 
 ## Description

diff --git a/public/static/docs/command-reference/import.md b/public/static/docs/command-reference/import.md
@@ -14,8 +14,8 @@ import.
 usage: dvc import [-h] [-q | -v] [-o [OUT]] [--rev [REV]] url path
 
 positional arguments:
-  url              Location of DVC or Git repository to download from.
-  path             Path to a file or directory within the repository.
+  url              Location of DVC or Git repository to download from
+  path             Path to a file or directory within the repository
 ```
 
 ## Description

diff --git a/public/static/docs/command-reference/init.md b/public/static/docs/command-reference/init.md
@@ -22,11 +22,10 @@ scenarios like monorepos, automation, etc:
 - [Initializing DVC without Git](#how-does-it-affect-dvc-commands) - support for
   SCM other than Git, deployment automation cases, etc.
 
-After DVC initialization, a new directory `.dvc/` will be created with the
-`config` and `.gitignore` files. These and other files and directories are
-hidden from user, as typically there's no need to interact with them directly.
-See [DVC Files and Directories](/doc/user-guide/dvc-files-and-directories) to
-learn more.
+At DVC initialization, a new `.dvc/` directory will be created for internal
+configuration and cache
+[files and directories](/doc/user-guide/dvc-files-and-directories) that are
+hidden from the user.
 
 ### Initializing DVC in subdirectories
 

diff --git a/public/static/docs/command-reference/metrics/add.md b/public/static/docs/command-reference/metrics/add.md
@@ -1,6 +1,7 @@
 # metrics add
 
-Mark the file located at `path` as a metric file.
+Mark <abbr>output</abbr> file as a
+[project metric](/doc/command-reference/metrics).
 
 ## Synopsis
 
@@ -14,25 +15,25 @@ positional arguments:
 ## Description
 
 Sets the `metric` field in the [DVC-file](/doc/user-guide/dvc-file-format) that
-defines the given `path` as an <abbr>output</abbr>, marking `path` as a
-[project metric](/doc/command-reference/metrics) to track.
+defines the given `path` as an <abbr>output</abbr>, marking `path` as a metric
+file to track.
 
 Note that outputs can also be marked as metrics via the `-m` or `-M` options of
 the `dvc run` command.
 
 While any text file can be tracked as a metric file, we recommend using TSV,
 CSV, or JSON formats. DVC provides a way to parse those formats to get to a
-specific value, if the file contains multiple metrics. See `dvc metrics show`
-for more details.
+specific value, if the file contains multiple metrics. See the
+[options](#options) below and `dvc metrics show` for more info.
 
 > Note that [external output](/doc/user-guide/managing-external-data) cannot be
 > marked as project metrics.
 
 ## Options
 
-- `-t`, `--type` - specify a type of the metric file. Accepted values are: `raw`
-  (default), `json`, `tsv`, `htsv`, `csv`, `hcsv`. It will be saved into the
-  corresponding DVC-file, and used by `dvc metrics show` to determine how to
+- `-t`, `--type` - specify a type for the metric file. Accepted values are:
+  `raw` (default), `json`, `tsv`, `htsv`, `csv`, `hcsv`. It will be saved into
+  the corresponding DVC-file, and used by `dvc metrics show` to determine how to
   handle displaying metrics.
 
   `raw` means that no additional parsing is applied, and `--xpath` is ignored.

diff --git a/public/static/docs/command-reference/metrics/diff.md b/public/static/docs/command-reference/metrics/diff.md
@@ -1,6 +1,6 @@
 # metrics diff
 
-Show changes in [metrics](/doc/command-reference/metrics#description) between
+Show changes in [project metrics](/doc/command-reference/metrics), between
 commits in the <abbr>DVC repository</abbr>, or between a commit and the
 <abbr>workspace</abbr>.
 

diff --git a/public/static/docs/command-reference/metrics/index.md b/public/static/docs/command-reference/metrics/index.md
@@ -1,6 +1,6 @@
 # metrics
 
-A set of commands to collect and display project metrics:
+A set of commands to add, manage, collect, and display project metrics:
 [add](/doc/command-reference/metrics/add),
 [show](/doc/command-reference/metrics/show),
 [diff](/doc/command-reference/metrics/diff),
@@ -16,7 +16,7 @@ positional arguments:
   COMMAND
     show                Output metric values.
     add                 Tag file as a metric file.
-    modify              Modify metric file options.
+    modify              Modify metric file values.
     remove              Remove files's metric tag.
 ```
 

diff --git a/public/static/docs/command-reference/metrics/modify.md b/public/static/docs/command-reference/metrics/modify.md
@@ -1,7 +1,7 @@
 # metrics modify
 
-Modify [project metric](/doc/command-reference/metrics) values such as type,
-path expression that is used to parse it, etc. (See full options below.)
+Modify [project metric](/doc/command-reference/metrics) default formatting with
+options such as `type` or `xpath`. See full [options](#options) info below.
 
 ## Synopsis
 
@@ -15,10 +15,9 @@ positional arguments:
 ## Description
 
 This command finds a corresponding [DVC-file](/doc/user-guide/dvc-file-format)
-for the provided metric file `path` – the one that defines `path` among its
-<abbr>outputs</abbr>, see `dvc metrics add` or the `-m` and `-M` options of
-`dvc run` – and updates the specification of the metric. (See full options
-below.)
+for the provided metric file (`path` is defined among the <abbr>outputs</abbr>
+of the DVC-file), and updates the default formatting of the metric. (See the
+[options](#options) below and `dvc metrics show` for more info.)
 
 If `path` isn't tracked by DVC (described in one of the <abbr>workspace</abbr>
 DVC-files), the following error will be raised:
@@ -33,9 +32,9 @@ ERROR: failed to modify metric file settings -
 
 ## Options
 
-- `-t`, `--type` - specify a type of the metric file. Accepted values are: `raw`
-  (default), `json`, `tsv`, `htsv`, `csv`, `hcsv`. It will be saved into the
-  corresponding DVC-file, and used by `dvc metrics show` to determine how to
+- `-t`, `--type` - specify a type for the metric file. Accepted values are:
+  `raw` (default), `json`, `tsv`, `htsv`, `csv`, `hcsv`. It will be saved into
+  the corresponding DVC-file, and used by `dvc metrics show` to determine how to
   handle displaying metrics.
 
   `raw` means that no additional parsing is applied, and `--xpath` is ignored.

diff --git a/public/static/docs/command-reference/metrics/remove.md b/public/static/docs/command-reference/metrics/remove.md
@@ -1,7 +1,8 @@
 # metrics remove
 
 Stop tracking a [project metric](/doc/command-reference/metrics): Keeps file
-located at `path` an <abbr>output</abbr>, but removes its metric mark.
+located at `path` as an <abbr>output</abbr>, but removes its metric mark in the
+DVC-file.
 
 ## Synopsis
 
@@ -16,9 +17,8 @@ positional arguments:
 ## Description
 
 This command finds a corresponding [DVC-file](/doc/user-guide/dvc-file-format)
-for the provided metric file `path` – the one that defines `path` among its
-<abbr>outputs</abbr>, see `dvc metrics add` or the `-m` and `-M` options of
-`dvc run` – and resets the `metric` field for the provided output.
+for the provided metric file (`path` is defined among the <abbr>outputs</abbr>
+of the DVC-file), and resets the `metric` field for the file.
 
 This does not remove or delete the file in question. It only unmarks it as a
 metric file. It also keeps the file as an output of the corresponding DVC-file.

diff --git a/public/static/docs/command-reference/metrics/show.md b/public/static/docs/command-reference/metrics/show.md
@@ -1,17 +1,17 @@
 # metrics show
 
-Find and print [project metrics](/doc/command-reference/metrics), with optional
+Print [project metrics](/doc/command-reference/metrics), with optional
 formatting.
 
 ## Synopsis
 
 ```usage
-usage: dvc metrics show [-h] [-q | -v] [-t TYPE] [-x XPATH] [-a] [-T] [-R]
+usage: dvc metrics show [-h] [-q | -v]
+                        [-t TYPE] [-x XPATH] [-a] [-T] [-R]
                         [targets [targets ...]]
 
 positional arguments:
-  targets               Metric files or directories (see -R) to show (leave
-                        empty to display all)
+  targets               Metric files or directories (see -R) to show
 ```
 
 ## Description
@@ -43,9 +43,9 @@ compares them with a previous version.
 
 ## Options
 
-- `-t`, `--type` - specify a type of the metric file. Accepted values are: `raw`
-  (default), `json`, `tsv`, `htsv`, `csv`, `hcsv`. It will be used to determine
-  how to parse and format metics for display.
+- `-t`, `--type` - specify a type for the metric file. Accepted values are:
+  `raw` (default), `json`, `tsv`, `htsv`, `csv`, `hcsv`. It will be used to
+  determine how to parse and format metics for display.
 
   `raw` means that no additional parsing is applied, and `--xpath` is ignored.
   `htsv`/`hcsv` are the same as `tsv`/`csv`, but the values in the first row of

diff --git a/public/static/docs/command-reference/move.md b/public/static/docs/command-reference/move.md
@@ -1,9 +1,9 @@
 # move
 
-Renames a file or a directory and modifies the corresponding
+Rename a file or a directory and modify the corresponding
 [DVC-file](/doc/user-guide/dvc-file-format) (see `dvc add`) to reflect the
 change. If the file or directory has the same name as the corresponding
-DVC-file, it would also rename the DVC-file.
+DVC-file, it also renames it.
 
 ## Synopsis
 

diff --git a/public/static/docs/command-reference/pipeline/list.md b/public/static/docs/command-reference/pipeline/list.md
@@ -1,7 +1,6 @@
 # pipeline list
 
-Show connected groups (pipelines) of [stage](/doc/command-reference/run) that
-are independent of each other.
+List connected groups of [stages](/doc/command-reference/run) (pipelines).
 
 ## Synopsis
 

diff --git a/public/static/docs/command-reference/pull.md b/public/static/docs/command-reference/pull.md
@@ -1,9 +1,9 @@
 # pull
 
-Downloads missing files and directories from
-[remote storage](/doc/command-reference/remote) to the <abbr>cache</abbr> based
-on [DVC-files](/doc/user-guide/dvc-file-format) in the <abbr>workspace</abbr>,
-then links the downloaded files into the workspace.
+Download tracked files or directories from
+[remote storage](/doc/command-reference/remote) to the <abbr>cache</abbr> and
+<abbr>workspace</abbr>, based on the current
+[DVC-files](/doc/user-guide/dvc-file-format).
 
 ## Synopsis
 
@@ -20,8 +20,8 @@ positional arguments:
 ## Description
 
 The `dvc pull` and `dvc push` commands are the means for uploading and
-downloading data to and from remote storage. These commands are analogous to the
-`git pull` and `git push` commands.
+downloading data to and from remote storage. These commands are analogous to
+`git pull` and `git push`, respectively.
 [Data sharing](/doc/use-cases/sharing-data-and-model-files) across environments
 and preserving data versions (input datasets, intermediate results, models,
 [metrics](/doc/command-reference/metrics), etc) remotely (S3, SSH, GCS, etc.)

diff --git a/public/static/docs/command-reference/push.md b/public/static/docs/command-reference/push.md
@@ -1,6 +1,6 @@
 # push
 
-Uploads files or directories tracked by DVC to
+Upload tracked files or directories to
 [remote storage](/doc/command-reference/remote).
 
 ## Synopsis
@@ -17,9 +17,9 @@ positional arguments:
 
 ## Description
 
-The `dvc push` command is the twin pair to the `dvc pull` command, and together
-they are the means for uploading and downloading data to and from remote
-storage, respectively.
+The `dvc pull` and `dvc push` commands are the means for uploading and
+downloading data to and from remote storage. These commands are analogous to
+`git pull` and `git push`, respectively.
 [Data sharing](/doc/use-cases/sharing-data-and-model-files) across environments
 and preserving data versions (input datasets, intermediate results, models,
 [metrics](/doc/command-reference/metrics), etc) remotely (S3, SSH, GCS, etc.)

diff --git a/public/static/docs/command-reference/remote/default.md b/public/static/docs/command-reference/remote/default.md
@@ -1,6 +1,6 @@
 # remote default
 
-Set/unset a default data remote.
+Set/unset the default data remote.
 
 > Depending on your remote storage type, you may also need `dvc remote modify`
 > to provide credentials and/or configure other remote parameters.

diff --git a/public/static/docs/command-reference/remote/list.md b/public/static/docs/command-reference/remote/list.md
@@ -1,6 +1,6 @@
 # remote list
 
-Show all available data remotes.
+List all available data remotes.
 
 See also [add](/doc/command-reference/remote/add),
 [default](/doc/command-reference/remote/default),

diff --git a/public/static/docs/command-reference/remote/modify.md b/public/static/docs/command-reference/remote/modify.md
@@ -1,6 +1,6 @@
 # remote modify
 
-Modify configuration of data remotes.
+Modify the configuration of a data remote.
 
 > This command is commonly needed after `dvc remote add` or
 > [default](/doc/command-reference/remote/default) to setup credentials or other

diff --git a/public/static/docs/command-reference/remote/remove.md b/public/static/docs/command-reference/remote/remove.md
@@ -1,7 +1,7 @@
 # remote remove
 
-Remove a data remotes. This command affects DVC configuration files only, it
-does not physically remove data files stored remotely.
+Remove a data remote. This command affects DVC configuration files only, it does
+not physically remove data files stored remotely.
 
 See also [add](/doc/command-reference/remote/add),
 [default](/doc/command-reference/remote/default),

diff --git a/public/static/docs/command-reference/repro.md b/public/static/docs/command-reference/repro.md
@@ -1,7 +1,7 @@
 # repro
 
 Reproduce complete or partial [pipelines](/doc/command-reference/pipeline) by
-executing commands defined in their [stages](/doc/command-reference/run), in the
+executing commands defined in their [stages](/doc/command-reference/run) in the
 correct order. The commands to be executed are determined by recursively
 analyzing dependencies and <abbr>outputs</abbr> of the target stages.
 
@@ -149,7 +149,7 @@ and only execute the final stage.
 - `-q`, `--quiet` - do not write anything to standard output. Exit with 0 if all
   stages are up to date or if all stages are successfully executed, otherwise
   exit with 1. The command defined in the stage is free to write output
-  irregardless of this flag.
+  regardless of this flag.
 
 - `-v`, `--verbose` - displays detailed tracing information.
 

diff --git a/public/static/docs/command-reference/root.md b/public/static/docs/command-reference/root.md
@@ -1,6 +1,6 @@
 # root
 
-Returns relative path to the <abbr>DVC project</abbr>.
+Return the relative path to the <abbr>DVC project</abbr>.
 
 ## Synopsis
 

diff --git a/public/static/docs/command-reference/status.md b/public/static/docs/command-reference/status.md
@@ -19,11 +19,12 @@ positional arguments:
 ## Description
 
 `dvc status` searches for changes in the existing pipelines, either showing
-which [stages](/doc/command-reference/run) have changed in the workspace
-(including uncommitted local changes) and must be reproduced (with `dvc repro`),
-or differences between <abbr>cache</abbr> vs. remote storage (meaning `dvc push`
-or `dvc pull` should be run to synchronize them). The two modes, _local_ and
-_cloud_ are triggered by using the `--cloud` or `--remote` options:
+which [stages](/doc/command-reference/run) have changed in the workspace (not
+yet tracked by DVC) and must be added again (with `dvc add`) or reproduced (with
+`dvc repro`); or differences between <abbr>cache</abbr> vs. remote storage
+(meaning `dvc push` or `dvc pull` should be run to synchronize them). The two
+modes, _local_ and _cloud_ are triggered by using the `--cloud` or `--remote`
+options:
 
 | Mode   | CLI Option | Description                                                                                                                 |
 | ------ | ---------- | --------------------------------------------------------------------------------------------------------------------------- |