ref: rephrase list Desc for clarity on it's purpose and scope

per dvc/issues/5640

content/docs/command-reference/list.md

@@ -1,7 +1,9 @@
 # list
 
-List repository contents, including files, models, and directories tracked by
-DVC (as <abbr>outputs</abbr>) and by Git.
+List project contents, including files, models, and directories tracked by DVC
+and by Git.
+
+> Useful to find data to `dvc get`, `dvc import`, or for `dvc.api` functions.
 
 ## Synopsis
 
@@ -16,17 +18,15 @@ positional arguments:
 
 ## Description
 
-A side-effect of DVC is that it hides actual data paths, by effectively
-replacing files and directories with <abbr>DVC files</abbr>. So you don't see
-data files/dirs when you browse a <abbr>DVC repository</abbr> on Git hosting
-(e.g. GitHub), you just see the `dvc.yaml` and `.dvc` files. This can make it
-hard to navigate the project, for example to find files or directories for use
-with `dvc get`, `dvc import`, or `dvc.api` functions.
+Produces a view of a <abbr>DVC repository</abbr> (usually online), listing data
+files and directories tracked by DVC alongside the remaining Git repo contents.
+This is useful because when you browse a hosted repository (e.g. on GitHub or
+with `git ls-remote`), you only see the `dvc.yaml` and `.dvc` files with your
+code (files tracked by Git).
 
-This command produces a view of a DVC repository, as if files and directories
-tracked by DVC were found directly in the Git repo. Its output is equivalent to
-cloning the repo and [pulling](/doc/command-reference/pull) the data (except
-that nothing is downloaded by `dvc list`), like this:
+This command's output is equivalent to cloning the repo and
+[pulling](/doc/command-reference/pull) the data (except that nothing is
+downloaded), like this:
 
 ```dvc
 $ git clone <url> example
@@ -35,17 +35,17 @@ $ dvc pull
 $ ls <path>
 ```
 
-Only the root directory is listed by default, but the `-R` option can be used to
-list files recursively.
-
 The `url` argument specifies the address of the DVC or Git repository containing
 the data source. Both HTTP and SSH protocols are supported (e.g.
 `[user@]server:project.git`). `url` can also be a local file system path
 (including the current project e.g. `.`).
 
 The optional `path` argument is used to specify a directory to list within the
-source repository at `url` (including paths inside tracked directories). It's
-similar to providing a path to list to commands such as `ls` or `aws s3 ls`.
+Git repo at `url` (including paths inside tracked directories). It's similar to
+providing a path to list to commands such as `ls` or `aws s3 ls`.
+
+Only the root directory is listed by default, but the `-R` option can be used to
+list files recursively.
 
 Please note that `dvc list` doesn't check whether the listed data (tracked by
 DVC) actually exists in remote storage, so it's not guaranteed whether it can be