diff --git a/static/docs/commands-reference/status.md b/static/docs/commands-reference/status.md
index 75adcadd1e..3c1210c99d 100644
--- a/static/docs/commands-reference/status.md
+++ b/static/docs/commands-reference/status.md
@@ -45,25 +45,50 @@ detected, `dvc status` prints this message:
```dvc
$ dvc status
- Pipeline is up to date. Nothing to reproduce.
+ Pipelines are up to date. Nothing to reproduce.
```
-This says that no differences were detected, and therefore that no stages would
-be run again if `dvc repro` were executed.
+This indicates that no differences were detected, and therefore no stages would
+be run again by `dvc repro`.
If instead, differences are detected, `dvc status` lists those changes. For each
-DVC-file (stage) with differences, the _dependencies_ and/or _outputs_ that
-differ are listed. For each item listed, either the file name or the checksum is
-shown, and additionally a status word is shown describing the change:
-
-- For the local workspace:
- - _changed_ means the file has changed
-- For comparison against a remote cache:
- - _new_ means the file exists in the local cache but not the remote cache
- - _deleted_ means the file doesn't exist in the local cache, but exists in the
- remote cache
+DVC-file (stage) with differences, the changes in _dependencies_ and/or
+_outputs_ that differ are listed. For each item listed, either the file name or
+the checksum is shown, and additionally a status word is shown describing the
+changes. This changes list provides a reference to both the status of a
+DVC-file, as well as the changes to individual dependencies and outputs
+described in it:
+
+- _changed checksum_ means that the DVC-file checksum has changed
+ (e.g. someone manually edited the file)
+
+- _always changed_ means that this is a special DVC-file with no dependencies
+ (orphans), which is considered always changed and is always executed by `dvc
+ repro`
+
+- _changed deps_ or _changed outs_ means that there are changes in dependencies
+ or outputs defined by the DVC-file. Depending on the use case,
+ commands like `dvc commit` or `dvc repro`, `dvc run` should be run to update
+ the file. Possible states are:
+
+ - _new_: output exists in workspace, but there is no corresponding checksum
+ calculated and saved in the DVC-file for this output yet
-For the _changed_ case, the `dvc repro` command is indicated.
+ - _modified_: output or dependency exists in workspace, but the
+ corresponding checksum in the DVC-file is not up to date
+
+ - _deleted_: output or dependency does not exist in workspace, but still
+ referred in the DVC-file
+
+ - _not in cache_: output exists in workspace and the corresponding checksum
+ in the DVC-file is up to date, but there is no corresponding
+ cache entry
+
+**For comparison against a remote cache:**
+
+- _new_ means the file exists in the local cache but not the remote cache
+- _deleted_ means the file doesn't exist in the local cache, but exists in the
+ remote cache
For either the _new_ and _deleted_ cases, the local cache (subset of it, that is
determined by the active workspace) is different from the remote cache. Bringing
@@ -118,14 +143,19 @@ cache. For the typical process to update workspaces, see
```dvc
$ dvc status
- bar.dvc
- outs
- changed: bar
- deps
- changed: foo
- foo.dvc
- outs
- changed: foo
+bar.dvc:
+ changed deps:
+ modified: bar
+ changed outs:
+ not in cache: foo
+foo.dvc
+ changed outs:
+ deleted: foo
+ changed checksum
+prepare.dvc
+ changed outs:
+ new: bar
+ always changed
```
This shows that for `bar.dvc` the dependency, `foo`, has changed, and the
@@ -143,8 +173,8 @@ Pipeline is up to date. Nothing to reproduce.
$ dvc status model.p.dvc --with-deps
matrix-train.p.dvc
- deps
- changed: code/featurization.py
+ changed deps:
+ modified: code/featurization.py
```
If the `dvc status` command is limited to a target that had no changes, result