Plot: 2nd round of review

iterative · Apr 29, 2020 · 70339ab · 70339ab
1 parent facc7a8
commit 70339ab
Show file tree

Hide file tree

Showing 3 changed files with 32 additions and 32 deletions.
diff --git a/content/docs/command-reference/plot/diff.md b/content/docs/command-reference/plot/diff.md
@@ -1,9 +1,8 @@
 # plot diff
 
-Show difference in
+Show multiple versions of
 [continuous metrics](/doc/command-reference/plot#continous-metrics) by plotting
-on a single [plot](/doc/command-reference/plot) different versions of metrics
-from the <abbr>DVC repository</abbr> or workspace.
+them in a single image.
 
 ## Synopsis
 
@@ -47,7 +46,7 @@ an output.
 
 - `-t [TEMPLATE], --template [TEMPLATE]` - File to be injected with data.
 
-- `-d [DATAFILE], --datafile [DATAFILE]` - Data to be visualized.
+- `-d [DATAFILE], --datafile [DATAFILE]` - Continuous metrics file to visualize.
 
 - `-r RESULT, --result RESULT` - Name of the generated file.
 

diff --git a/content/docs/command-reference/plot/index.md b/content/docs/command-reference/plot/index.md
@@ -2,7 +2,7 @@
 
 Contains commands to visualize
 [continuous metrics](/doc/command-reference/plot#continuous-metrics) in
-structured files like JSON, CSV, TSV: [show](/doc/command-reference/plot/show),
+structured files (JSON, CSV, or TSV): [show](/doc/command-reference/plot/show),
 [diff](/doc/command-reference/plot/diff).
 
 ## Synopsis
@@ -12,23 +12,34 @@ usage: dvc plot [-h] [-q | -v] {show,diff} ...
 
 positional arguments:
   COMMAND
-    show         Plot data from a file
-    diff         Plot changes between commits in the DVC repository,
-                 or between the last commit and the workspace.
+    show         Generate a plot image file from a continuous metrics file.
+    diff         Plot continuous metrics differences between commits in the DVC
+                 repository, or between the last commit and the workspace.
 ```
 
 ## Description
 
-DVC provides a set of commands to visualize continuous metrics of machine
-learning experiments in. Usual examples of plots are AUC curves, loss functions,
+DVC provides a set of commands to visualize _continuous metrics_ of machine
+learning experiments. Usual examples of plots are AUC curves, loss functions,
 and confusion matrices.
 
-The continuous metrics should be saved in files which are usually created by
-users or generated by user's modeling or data processing code. The plot commands
-can work with these files commited to a repository history, data files
-controlled by DVC or files from workspace.
+Continous metrics represents a plot and should be stored as data series in one
+of the supported [file formats](#file-formats). These files are usually created
+by users or generated by user's modeling or data processing code.
 
-### Continuous metrics
+The plot commands can work with these continuous metrics files that are commited
+to a repository history, data files controlled by DVC or files from workspace.
+For examlpe, the command `dvc plot diff` generates a plot with two versions of
+the metrics:
+
+```dvc
+$ dvc plot diff -d logs.csv
+file:///Users/dmitry/src/plot/logs.html
+```
+
+![](/img/plot_auc.svg)
+
+### Difference between continuous and scolar metrics
 
 DVC has two concepts for metrics for representing result of machine learning
 training or data processing:
@@ -38,28 +49,18 @@ training or data processing:
 2. `dvc plot` to visualize continuous metrics such as AUC curve, loss function,
    confusion matrixes and others.
 
-Scalar metrics should be stored in a hirarchical files such as JSON and YAML and
-`dvc metrics diff` command can represent difference between the metrics in
-different experiments as a float numbers. Like `AUC` metrics is `0.801807` and
-was increase by `+0.037826` from the previous value:
+In contrast to continuous metrics, scalar metrics should be stored in a
+hirarchical files such as JSON and YAML and `dvc metrics diff` command can
+represent difference between the metrics in different experiments as a float
+numbers. Like `AUC` metrics is `0.801807` and was increase by `+0.037826` from
+the previous value:
 
 ```dvc
 $ dvc metrics diff
     Path       Metric    Value      Change
 summary.json   AUC      0.801807   0.037826
 ```
 
-In contrast to scalar metrics, continous metrics represents a plot and should be
-stored as an array in JSON file or as a column in CSV or TSV files. The command
-`dvc plot diff` generates a plot with two versions of the metrics:
-
-```dvc
-$ dvc plot diff -d logs.csv
-file:///Users/dmitry/src/plot/logs.html
-```
-
-![](/img/plot_auc.svg)
-
 ### File formats
 
 Supported file formats for continuous metrics are: JSON, CSV, TSV. DVC expects

diff --git a/content/docs/command-reference/plot/show.md b/content/docs/command-reference/plot/show.md
@@ -1,7 +1,7 @@
 # plot show
 
-Generate a [plot](/doc/command-reference/plot) from a file with
-[continuous metrics](/doc/command-reference/plot#continous-metrics).
+Generate a plot image from from a
+[continuous metrics](/doc/command-reference/plot#continous-metrics) file.
 
 ## Synopsis