metrics(plots): regular udpates & terminology

content/docs/command-reference/metrics/diff.md

@@ -1,6 +1,6 @@
 # metrics diff
 
-Show changes in [metrics](/doc/command-reference/metrics) between commits in the
+Compare [metrics](/doc/command-reference/metrics) between two commits in the
 <abbr>DVC repository</abbr>, or between a commit and the <abbr>workspace</abbr>.
 
 ## Synopsis
@@ -21,23 +21,18 @@ positional arguments:
 ## Description
 
 This command provides a quick way to compare metrics among experiments in the
-repository history. It requires that Git is being used to version the metrics.
+repository history. All metrics defined in `dvc.yaml` are used by default. The
+comparison shown by this command includes the new value, and the
+numeric difference (delta, rounded to 5 digits precision).
 
-> This kind of metrics can be defined with the `-m` (`--metrics`) and `-M`
-> (`--metrics-no-cache`) options of `dvc run`.
-
-Run without arguments, this command compares metrics currently present in the
-<abbr>workspace</abbr> uncommitted changes) with the latest committed version.
-
-The differences shown by this command include the new value, and numeric
-difference (delta) from the previous value of metrics (rounded to 5 digits
-precision). They're calculated between two commits (hash, branch, tag, or any
-[Git revision](https://git-scm.com/docs/revisions)) for all metrics in the
-<abbr>project</abbr>, found by examining all of the `dvc.yaml` and `.dvc` files
-in both versions.
+`a_rev` and `b_rev` are Git commit hashes, tag, or branch names. If none are
+specified, `dvc metrics diff` compares metrics currently present in the
+<abbr>workspace</abbr> (uncommitted changes) with the latest committed versions
+(required). A single specified revision results in comparing the workspace and
+that version.
 
 Another way to display metrics is the `dvc metrics show` command, which just
-lists all the current metrics without comparisons.
+lists all the current metrics, without comparisons.
 
 ## Options
 

content/docs/command-reference/metrics/index.md

@@ -32,8 +32,9 @@ ability to mark a certain stage <abbr>outputs</abbr> as metrics. These metrics
 are project-specific floating-point or integer values e.g. AUC, ROC, false
 positives, etc.
 
-This kind of metrics can be defined with the `-m` (`--metrics`) and `-M`
-(`--metrics-no-cache`) options of `dvc run`.
+This type of metrics files are typically generated by user data processing code,
+and are tracked using the `-m` (`--metrics`) and `-M` (`--metrics-no-cache`)
+options of `dvc run`.
 
 In contrast to `dvc plots`, these metrics should be stored in hierarchical
 files. Unlike its `dvc plots` counterpart, `dvc metrics diff` can report the

content/docs/command-reference/metrics/show.md

@@ -19,9 +19,6 @@ positional arguments:
 Finds and prints all metrics in the <abbr>project</abbr> by examining all of its
 [DVC-files](/doc/user-guide/dvc-files-and-directories).
 
-> This kind of metrics can be defined with the `-m` (`--metrics`) and `-M`
-> (`--metrics-no-cache`) options of `dvc run`.
-
 If `targets` are provided, it will show those specific metric files instead.
 With the `-a` or `-T` options, this command shows the different metrics values
 across all Git branches or tags, respectively. With the `-R` option, some of the

content/docs/command-reference/plots/diff.md

@@ -1,7 +1,7 @@
 # plots diff
 
 Show multiple versions of [plot metrics](/doc/command-reference/plots) by
-plotting them in a single image. This allows to easily compare them.
+overlaying them in a single plot. This allows to compare them easily.
 
 ## Synopsis
 
@@ -24,7 +24,7 @@ experiments in the <abbr>repository</abbr> history, by plotting multiple
 versions of the metrics. All plots defined in `dvc.yaml` are used by default.
 
 > Note that unlike `dvc metrics diff`, this command does not calculate numeric
-> differences between metric file values.
+> differences between metrics file values.
 
 `revisions` are Git commit hashes, tag, or branch names. If none are specified,
 `dvc plots diff` compares targets currently present in the
@@ -33,7 +33,7 @@ versions (required). A single specified revision results in comparing the
 workspace and that version.
 
 Note that any number of `revisions` can be provided, and the resulting plot
-shows all of them in a single output.
+shows all of them in a single image.
 
 The plot style can be customized with
 [plot templates](/doc/command-reference/plots#plot-templates), using the
@@ -43,6 +43,9 @@ please see `dvc plots`.
 > Note that the default behavior of this command can be modified per metrics
 > file with `dvc plots modify`.
 
+Another way to display plots is the `dvc plots show` command, which just lists
+all the current plots, without comparisons.
+
 ## Options
 
 - `--targets <path>` - specific metric files to visualize. These must be listed

content/docs/command-reference/plots/index.md

@@ -33,9 +33,11 @@ DVC provides a set of commands to visualize metrics of machine learning
 experiments. Usual plot examples are AUC curves, loss functions, confusion
 matrices, among others.
 
-This kind of metric files are created by users, or generated by user data
-processing code. `dvc plots` subcommands can work with metric files committed to
-a Git repo history, data files controlled by DVC, or any other file in system.
+This type of metrics files are created by users, or generated by user data
+processing code, and get defined with the `-p` (`--plots`) and
+`--plots-no-cache`) options of `dvc run`. `dvc plots` subcommands can work with
+plots files committed to a Git repo history, data files controlled by DVC, or
+any other file in system.
 
 DVC generates plots as HTML files that can be open with a web browser. These
 HTML files use [Vega-Lite](https://vega.github.io/vega-lite/). Vega is a

content/docs/user-guide/how-to/undo-adding-data.md

@@ -13,7 +13,7 @@ data.csv    data.csv.dvc
 ```
 
 > Note, if you are using `symlink` or `hardlink` as
-> [link type](doc/user-guide/large-dataset-optimization#file-link-types-for-the-dvc-cache)
+> [link type](/doc/user-guide/large-dataset-optimization#file-link-types-for-the-dvc-cache)
 > for DVC <abbr>cache</abbr>, you will have to unprotect the tracked file first
 > (see `dvc unprotect`):
 >