iterative · jorgeorpinel · Mar 19, 2021 · Mar 13, 2021 · Mar 14, 2021 · Mar 14, 2021
diff --git a/content/docs/command-reference/add.md b/content/docs/command-reference/add.md
@@ -153,10 +153,12 @@ not.
   > Additionally, this typically requires an external cache setup (see link
   > above).
 
-- `-o <path>`, `--out <path>` - destination `path` to make a local target copy,
-  or to [transfer](#example-transfer-to-cache) an external target into the cache
-  (and link to workspace). Note that this can be combined with `--to-remote` to
-  avoid storing the data locally, while still adding it to the project.
+- `-o <path>`, `--out <path>` - destination `path` inside the workspace to link
+  (or copy) a data target, which will now be tracked by DVC. Note that combining
+  this with an
+  [external cache transfer](#example-transfer-to-an-external-cache), or with the
+  `--to-remote` option, let's you avoid storing an external target locally,
+  while still adding it to the project.
 
 - `--to-remote` - import an external target, but don't move it into the
   workspace, nor cache it. [Transfer it](#example-transfer-to-remote-storage) it
@@ -336,28 +338,21 @@ $ tree .dvc/cache
 Only the hash values of the `dir/` directory (with `.dir` file extension) and
 `file2` have been cached.
 
-## Example: Transfer to the cache
+## Example: Transfer to an external cache
 
-When you have a large dataset in an external location, you may want to add it to
-the <abbr>project</abbr> without having to copy it into the workspace. Maybe
-your local disk doesn't have enough space, but you have setup an
-[external cache](/doc/use-cases/shared-development-server#configure-the-external-shared-cache)
-that could handle it.
+Sometimes you may want to add a large dataset currently found in an external
+location, so it becomes local to the project. However, your local file system
+may not have enough space to download it — which is needed to add data in DVC,
+right? Not necessarily!
 
-The `--out` option lets you add external paths in a way that they are
+The `--out` option lets you add external data in a way that it's
 <abbr>cached</abbr> first, and then
 [linked](/doc/user-guide/large-dataset-optimization#file-link-types-for-the-dvc-cache)
-to a given path inside the <abbr>workspace<abbr>. Let's initialize an example
-DVC project to try this:
-
-```dvc
-$ mkdir example # workspace
-$ cd example
-$ git init
-$ dvc init
-```
+to a given path inside the <abbr>workspace</abbr>. Combined with an
+[external cache](/doc/use-cases/shared-development-server#configure-the-external-shared-cache)
+setup, this let's you avoid using your local file system completely.
 
-Now we can add a `data.xml` file via HTTP for example, putting it a local path
+For example, we can add a `data.xml` file via HTTP, outputting it a local path
 in our project:
 
 ```dvc
@@ -368,9 +363,10 @@ data.xml data.xml.dvc
 ```
 
 The resulting `.dvc` file will save the provided local `path` as if the data was
-already in the workspace, while the `md5` hash points to the copy of the data
-that has now been transferred to the <abbr>cache</abbr>. Let's check the
-contents of `data.xml.dvc` in this case:
+always in the workspace, while the `md5` hash points to the copy of the data
+that has now been transferred to the <abbr>cache</abbr> (which again, we assume
+it's already setup in some storage drive that can handle it). Let's check the
+contents of `data.xml.dvc`:
 
 ```yaml
 outs:
@@ -384,43 +380,37 @@ outs:
 
 ## Example: Transfer to remote storage
 
-When you have a large dataset in an external location, you may want to track it
-as if it was in your project, but without downloading it locally (for now). The
-`--to-remote` option lets you do so, while storing a copy
-[remotely](/doc/command-reference/remote) so it can be
-[pulled](/doc/command-reference/plots) later. Let's initialize a DVC project,
-and setup a remote:
+Similarly to the previous scenario, you may sometimes want to track a large
+dataset found externally into a regular <abbr>project</abbr> (with a local
+<abbr>cache</abbr>). Can it be done without downloading the data locally (for
+now)? Yes!
 
-```dvc
-$ mkdir example # workspace
-$ cd example
-$ git init
-$ dvc init
-$ mkdir /tmp/dvc-storage
-$ dvc remote add myremote /tmp/dvc-storage
-```
+The `--to-remote` option lets you transfer a copy of the target data to
+[remote storage](/doc/command-reference/remote), while creating a `.dvc` file
+locally so it can be [pulled](/doc/command-reference/plots) later. This is a way
+to "bootstrap" your project in your local machine, to be reproduced on the right
+environment later (e.g. a GPU cloud server or a CI/CD system).
 
-Now let's add the `data.xml` to our remote storage from the given remote
-location.
+Let's setup a simple remote and transfer a `data.xml` file from the web into it
+via DVC:
 
 ```dvc
+$ mkdir /tmp/dvc-storage
+$ dvc remote add myremote /tmp/dvc-storage
 $ dvc add https://data.dvc.org/get-started/data.xml -o data.xml \
                  --to-remote -r myremote
 ...
-```
-
-The only difference that dataset is transferred straight to remote, so DVC won't
-control the remote location you gave but rather continue managing your remote
-storage where the data is now on. The operation will still be resulted with an
-`.dvc` file:
-
-```dvc
 $ ls
 data.xml.dvc
 ```
 
-Whenever anyone wants to actually download the added data (for example from a
-system that can handle it), they can use `dvc pull` as usual:
+> Note that this can be combined with `--out` to specify a local destination
+> `path` (written to the `.dvc` file).
+
+DVC won't control the original data source after this, but rather continue
+managing your remote storage, where the data is now found. Whenever anyone wants
+to actually download the added data (from a system that can handle it), they can
+use `dvc pull` as usual:
 
 ```dvc
  $ dvc pull data.xml.dvc -r tmp_remote

diff --git a/content/docs/command-reference/config.md b/content/docs/command-reference/config.md
@@ -45,10 +45,10 @@ multiple projects and users, respectively:
   }
 </style>
 
-| Flag       | Priority | Mac location                           | Linux location (typical\*) | Windows location                                          |
-| ---------- | -------- | -------------------------------------- | -------------------------- | --------------------------------------------------------- |
-| `--global` | 3        | `$HOME/Library/Preferences/dvc/config` | `$HOME/.config/dvc/config` | `%LocalAppData%\iterative\dvc\config`                     |
-| `--system` | 4        | `/Library/Preferences/dvc/config`      | `/etc/xdg/dvc/config`      | `%AllUsersProfile%\Application Data\iterative\dvc\config` |
+| Flag       | Priority | Mac location                                    | Linux location (typical\*) | Windows location                                          |
+| ---------- | -------- | ----------------------------------------------- | -------------------------- | --------------------------------------------------------- |
+| `--global` | 3        | `$HOME/Library/Application\ Support/dvc/config` | `$HOME/.config/dvc/config` | `%LocalAppData%\iterative\dvc\config`                     |
+| `--system` | 4        | `/Library/Application\ Support/dvc/config`      | `/etc/xdg/dvc/config`      | `%AllUsersProfile%\Application Data\iterative\dvc\config` |
 
 > \* For Linux, the global `dvc/config` may be found in `$XDG_CONFIG_HOME`, and
 > the system-wide one in `$XDG_CONFIG_DIRS[0]`, if those env vars are defined.

diff --git a/content/docs/command-reference/get.md b/content/docs/command-reference/get.md
@@ -24,13 +24,13 @@ repository (e.g. source code, small image/other files). `dvc get` copies the
 target file or directory (found at `path` in `url`) to the current working
 directory. (Analogous to `wget`, but for repos.)
 
+> See `dvc list` for a way to browse repository contents to find files or
+> directories to download.
+
 > Note that unlike `dvc import`, this command does not track the downloaded
 > files (does not create a `.dvc` file). For that reason, it doesn't require an
 > existing DVC project to run in.
 
-> See `dvc list` for a way to browse repository contents to find files or
-> directories to download.
-
 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

diff --git a/content/docs/command-reference/import-url.md b/content/docs/command-reference/import-url.md
@@ -23,9 +23,8 @@ positional arguments:
 ## Description
 
 In some cases it's convenient to add a data file or directory from an external
-location into the workspace (or to
-[remote storage](/doc/command-reference/remote)), such that it can be updated
-later, if/when the external data source changes. Example scenarios:
+location into the project, such that it can be updated later if/when the
+external data source changes. Example scenarios:
 
 - A remote system may produce occasional data files that are used in other
   projects.
@@ -37,25 +36,27 @@ later, if/when the external data source changes. Example scenarios:
 
 `dvc import-url` helps you create such an external data dependency, without
 having to manually copy files from the supported locations (listed below), which
-may require installing a different tool for each type.
-
-When you don't want to store the target data in your local system, you can still
-create an import `.dvc` file while transferring a file or directory directly to
-remote storage, by using the `--to-remote` option. See the
-[Transfer to remote storage](#example-transfer-to-remote-storage) example for
-more details.
+would require installing/using a different tool for each type.
 
 The `url` argument specifies the external location of the data to be imported.
 The imported data is <abbr>cached</abbr>, and linked (or copied) to the current
-working directory with its original file name e.g. `data.txt` (or to a location
-provided with `out`).
+working directory with its original file name e.g. `data.txt`, or to a location
+provided with `out`.
 
 An _import `.dvc` file_ is created in the same location e.g. `data.txt.dvc` –
-similar to using `dvc add` after downloading the data. This makes it possible to
-update the import later, if the data source has changed (see `dvc update`).
+similar to using `dvc add` after downloading the data. It saves the information
+about the data source, so the import can be updated later if the data source has
+changed (see `dvc update`).
+
+💡 Using an
+[external cache](/doc/use-cases/shared-development-server#configure-the-external-shared-cache)
+or the `--to-remote` option lets you
+[transfer](#example-transfer-to-remote-storage) an import without using the
+local file system.
 
-> Note that the imported data can be [pushed](/doc/command-reference/push) to
-> remote storage normally.
+> Note that imported data can be [pushed](/doc/command-reference/push) and
+> [pulled](/doc/command-reference/pull) to/from
+> [remote storage](/doc/command-reference/remote) normally.
 
 `.dvc` files support references to data in an external location, see
 [External Dependencies](/doc/user-guide/external-dependencies). In such an
@@ -64,8 +65,9 @@ field contains the corresponding local path in the <abbr>workspace</abbr>. It
 records enough metadata about the imported data to enable DVC efficiently
 determining whether the local copy is out of date.
 
-Note that `dvc repro` doesn't check or update import `.dvc` files, use
-`dvc update` to bring the import up to date from the data source.
+Note that `dvc repro` doesn't check or update import `.dvc` files by default
+(see `dvc freeze`), use `dvc update` to bring the import up to date from the
+data source.
 
 DVC supports several types of external locations (protocols):
 
@@ -360,40 +362,33 @@ Running stage 'prepare' with command:
 
 ## Example: Transfer to remote storage
 
-When you have a large dataset in an external location, you may want to import it
-to your project without downloading it to the local file system (for using it
-later/elsewhere). The `--to-remote` option let you skip the download, while
-storing the imported data [remotely](/doc/command-reference/remote). Let's
-initialize a DVC project, and setup a remote:
+Normally, `dvc import-url` downloads the target data (to the <abbr>cache</abbr>)
+in order to link and track it locally. But what if there's not enough disk space
+for the download?
 
-```dvc
-$ mkdir example # workspace
-$ cd example
-$ git init
-$ dvc init
-$ mkdir /tmp/dvc-storage
-$ dvc remote add myremote /tmp/dvc-storage
-```
+One option is to setup an
+[external cache](/doc/use-cases/shared-development-server#configure-the-external-shared-cache)
+in a location that can handle the data. Another is to use the `--to-remote`
+option so the target data is transferred to
+[remote storage](/doc/command-reference/remote), while also tracked via an
+import `.dvc` file in the project.
 
-Now let's create an import `.dvc` file without downloading the target data,
-transferring it directly to remote storage instead:
+Let's setup a simple remote and create an import `.dvc` file without downloading
+the target data, transferring it directly to the remote:
 
 ```
+$ mkdir /tmp/dvc-storage
+$ dvc remote add myremote /tmp/dvc-storage
 $ dvc import-url https://data.dvc.org/get-started/data.xml data.xml \
                  --to-remote -r myremote
 ...
-```
-
-The only change in our local <abbr>workspace</abbr> is a newly created import
-`.dvc` file:
-
-```dvc
 $ ls
 data.xml.dvc
 ```
 
-Whenever anyone wants to actually download the imported data (for example from a
-system that can handle it), they can use `dvc pull` as usual:
+The only change in our local <abbr>workspace</abbr> is a the tiny `.dvc` file
+that was created. Whenever anyone wants to actually download the imported data
+(into a system that can handle it), they can use `dvc pull` as usual:
 
 ```
  $ dvc pull data.xml.dvc -r tmp_remote

diff --git a/content/docs/command-reference/import.md b/content/docs/command-reference/import.md
@@ -27,20 +27,25 @@ target file or directory (found at `path` in `url`), and tracks it in the local
 project. This makes it possible to update the import later, if the data source
 has changed (see `dvc update`).
 
-> Note that `dvc get` corresponds to the first step this command performs (just
-> download the data).
-
 > See `dvc list` for a way to browse repository contents to find files or
 > directories to import.
 
+> Note that `dvc get` corresponds to the first step this command performs (just
+> download the data).
+
 The imported data is <abbr>cached</abbr>, and linked (or copied) to the current
 working directory with its original file name e.g. `data.txt` (or to a location
 provided with `--out`). An _import `.dvc` file_ is created in the same location
 e.g. `data.txt.dvc` – similar to using `dvc add` after downloading the data.
 
-(ℹ️) DVC won't push or pull imported data to/from
-[remote storage](/doc/command-reference/remote), it will rely on it's original
-source.
+💡 Using an
+[external cache](/doc/use-cases/shared-development-server#configure-the-external-shared-cache)
+lets you transfer an import there (and link it in the <abbr>workspace</abbr>),
+without using the local file system.
+
+> Note that imported data can be [pushed](/doc/command-reference/push) and
+> [pulled](/doc/command-reference/pull) to/from
+> [remote storage](/doc/command-reference/remote) normally.
 
 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.
@@ -70,9 +75,9 @@ enable DVC efficiently determining whether the local copy is out of date.
 To actually [version the data](/doc/tutorials/get-started/data-versioning),
 `git add` (and `git commit`) the import `.dvc` file.
 
-Note that `dvc repro` doesn't check or update import `.dvc` files (see
-`dvc freeze`), use `dvc update` to bring the import up to date from the data
-source.
+Note that `dvc repro` doesn't check or update import `.dvc` files by default
+(see `dvc freeze`), use `dvc update` to bring the import up to date from the
+data source.
 
 Also note that chained imports (importing data that was imported into the source
 repo at `url`) are not supported.

diff --git a/content/docs/command-reference/plots/diff.md b/content/docs/command-reference/plots/diff.md
@@ -91,7 +91,7 @@ all the current plots, without comparisons.
   [Vega specification](https://vega.github.io/vega/docs/specification/) file
   instead of HTML. See `dvc plots` for more info.
 
-- `--open` - opens the generated plot directly in the browser.
+- `--open` - opens the generated plot in the browser automatically.
 
 - `--no-header` - lets DVC know that CSV or TSV `--targets` do not have a
   header. A 0-based numeric index can be used to identify each column instead of

diff --git a/content/docs/command-reference/plots/show.md b/content/docs/command-reference/plots/show.md
@@ -65,7 +65,7 @@ please see `dvc plots`.
   [Vega specification](https://vega.github.io/vega/docs/specification/) file
   instead of HTML. See `dvc plots` for more info.
 
-- `--open` - opens the generated plot directly in the browser.
+- `--open` - opens the generated plot in the browser automatically.
 
 - `--no-header` - lets DVC know that CSV or TSV `targets` do not have a header.
   A 0-based numeric index can be used to identify each column instead of names.

diff --git a/content/docs/user-guide/managing-external-data.md b/content/docs/user-guide/managing-external-data.md
@@ -1,13 +1,14 @@
 # External Outputs
 
 > ⚠️ This is an advanced feature for very specific situations and not
-> recommended except if there's absolutely no other alternative. In most cases
-> alternatives like the
-> [to-cache](/doc/command-reference/add#example-transfer-to-the-cache) or
-> [to-remote](/doc/command-reference/add#example-transfer-to-remote-storage)
-> strategies of `dvc add` and `dvc import-url` are more convenient. **Note**
-> that external outputs are not pushed or pulled from/to
+> recommended except if there's absolutely no other alternative. Note that
+> external outputs are not pushed or pulled from/to
 > [remote storage](/doc/command-reference/remote).
+>
+> In most cases the
+> [to-cache](/doc/command-reference/add#example-transfer-to-an-external-cache)
+> or [to-remote](/doc/command-reference/add#example-transfer-to-remote-storage)
+> strategies of `dvc add` and `dvc import-url` are more convenient.
 
 There are cases when data is so large, or its processing is organized in such a
 way, that its impossible to handle it in the local machine disk. For example