Restyle cmd-ref: plots: flexible plots docs (#3819)

* cmd-ref: plots: flexible plots docs

Related: treeverse/dvc#7477
Related: #2956

* Update content/docs/user-guide/project-structure/dvcyaml-files.md

* Apply suggestions from code review

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

* plots: examples: move to subcommands

* plots: refactor top-level plots definition

* plots: review refactor

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

* ref: fix a link (2/2)
per #3691 (review)

* ref: remove concept of type of metrics

* ref: term "plots files" (consistency)

* ref: wrap `plots index` usage block

* plots: top-level plots edits

* plots: improve motivation for top-level plots
per #3691 (review)

* ref: edit `plots show` desc

* ref: return plot template examples from `plots show` to index

* guide: move top-lv plot mention from stage entry to desc

* ref: clean up new `plots show` examples

* ref: more copy edits around plots

* Update content/docs/user-guide/project-structure/dvcyaml-files.md

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

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

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

* Restyled by prettier

Co-authored-by: Paweł Redzyński <[email protected]>
Co-authored-by: Jorge Orpinel <[email protected]>
Co-authored-by: Jorge Orpinel Perez <[email protected]>
Co-authored-by: Dave Berenbaum <[email protected]>
Co-authored-by: Restyled.io <[email protected]>
Co-authored-by: Dave Berenbaum <[email protected]>

Author: 6 people

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

@@ -15,26 +15,16 @@ positional arguments:
     diff                Show changes in metrics between commits.
 ```
 
-## Types of metrics
-
-DVC has two concepts for metrics, that represent different results of machine
-learning training or data processing:
-
-1. `dvc metrics` represent **scalar numbers** such as AUC, _true positive rate_,
-   etc.
-2. `dvc plots` can be used to visualize **data series** such as AUC curves, loss
-   functions, confusion matrices, etc.
-
 ## Description
 
 In order to follow the performance of machine learning experiments, DVC has the
 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 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 stage add`.
+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 stage add`.
 
 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/plots/diff.md

@@ -1,7 +1,7 @@
 # plots diff
 
-Show multiple versions of [plot metrics](/doc/command-reference/plots) by
-overlaying them in a single image. This allows to compare them easily.
+Show multiple versions of [plots](/doc/command-reference/plots) by overlaying
+them in a single image. This allows to compare them easily.
 
 ## Synopsis
 
@@ -123,11 +123,11 @@ file:///Users/usr/src/dvc_plots/index.html
 Compare two specific versions (commit hashes, tags, or branches):
 
 ```cli
-$ dvc plots diff HEAD 0135527 --targets logs.csv
+$ dvc plots diff HEAD^ 0135527 --targets logs.csv
 file:///Users/usr/src/dvc_plots/index.html
 ```
 
-![](/img/plots_diff.svg)
+![](/img/plots_diff_two_revs.svg)
 
 ## Example: Confusion matrix