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

* cmd-ref: plots: flexible plots docs Related: iterative/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]>
iterative · Jul 28, 2022 · c72dafc · c72dafc
1 parent f157a73
commit c72dafc
Show file tree

Hide file tree

Showing 21 changed files with 452 additions and 175 deletions.
diff --git a/content/docs/command-reference/metrics/index.md b/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

diff --git a/content/docs/command-reference/plots/diff.md b/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