iterative · jorgeorpinel · Feb 20, 2023 · Oct 13, 2022 · Oct 14, 2022 · Oct 17, 2022
diff --git a/content/docs/command-reference/config.md b/content/docs/command-reference/config.md
@@ -63,7 +63,7 @@ multiple projects or users, respectively.
 > Note that the `--show-origin` flag can show you where a given config option
 > `value` is currently stored.
 
-## Command options (flags)
+## Command options/flags
 
 - `-u`, `--unset` - remove the specified config option `name` from a config
   file. Don't provide a `value` argument when employing this flag.

diff --git a/content/docs/command-reference/remote/add.md b/content/docs/command-reference/remote/add.md
@@ -1,11 +1,15 @@
 # remote add
 
-Register a new [DVC remote](/doc/user-guide/data-management/remote-storage).
+Add a new `dvc remote` to the <abbr>project</abbr> configuration.
 
 <admon type="tip">
 
-Depending on your storage type, you may also need `dvc remote modify` to provide
-credentials and/or configure other remote parameters.
+You may also need `dvc remote modify` to provide credentials and/or configure
+other remote parameters. See [Remote storage configuration] for more
+information.
+
+[remote storage configuration]:
+  /doc/user-guide/data-management/remote-storage#configuration
 
 </admon>
 
@@ -23,41 +27,68 @@ positional arguments:
 
 ## Description
 
-This command creates a `remote` section in the <abbr>DVC project</abbr>'s
-[config file](/doc/command-reference/config) and optionally assigns a _default
-remote_ in the `core` section, if the `--default` option is used (recommended
-for the first remote):
+Registers an [additional storage] location to save data files (besides the
+<abbr>cache</abbr>) and optionally sets it as the `--default` remote. DVC
+remotes can point to a cloud storage service, an SSH server, network-attached
+storage, or even a directory in the local file system.
+
+[additional storage]: /doc/user-guide/data-management/remote-storage
+
+<admon type="tip">
+
+A [default remote] is expected by `dvc push`, `dvc pull`, `dvc status`,
+`dvc gc`, and `dvc fetch` unless their `--remote` option is used.
+
+[default remote]: /doc/command-reference/remote/default
+
+</admon>
+
+The remote `name` (required) is used to identify the remote and must be unique.
+DVC will determine the [type of remote](#supported-storage-types) based on the
+provided `url` (also required), a URL or path for the location.
+
+<admon type="info">
+
+The storage type determines which config parameters you can access via
+`dvc remote modify`. Note that the `url` itself can be modified.
+
+</admon>
+
+This command creates a [`remote`] section in the project's [config file]
+(`.dvc/config`). The `--default` (`-d`) flag uses the [`core`] config section:
+
+```cli
+$ dvc remote add -d temp /tmp/dvcstore
+```
 
 ```ini
-['remote "myremote"']
+# .dvc/config
+['remote "temp"']
     url = /tmp/dvcstore
 [core]
     remote = myremote
 ```
 
-> 💡 Default remotes are expected by commands that accept a `-r`/`--remote`
-> option (`dvc pull`, `dvc push`, `dvc status`, `dvc gc`, `dvc fetch`) when that
-> option is omitted.
+[config file]: /doc/command-reference/config
+[`remote`]: /doc/command-reference/config#remote
+[`core`]: /doc/command-reference/config#core
 
-`name` and `url` are required. The `name` is used to identify the remote and
-must be unique for the project.
+<admon type="info">
 
-`url` specifies a location to store your data. It can represent a cloud storage
-service, an SSH server, network-attached storage, or even a directory in the
-local file system (see all the supported remote storage types in the examples
-below).
+If you [installed DVC] via `pip` and plan to use cloud services as remote
+storage, you might need to install these optional dependencies: `[s3]`,
+`[azure]`, `[gdrive]`, `[gs]`, `[oss]`, `[ssh]`. Use `[all]` to include them
+all. For example:
 
-DVC will determine the [type of remote](#supported-storage-types) based on the
-`url` provided. This may affect which parameters you can access later via
-`dvc remote modify` (note that the `url` itself can be modified).
+```cli
+$ pip install "dvc[s3]"
+```
+
+[installed dvc]: /doc/install
 
-> If you installed DVC via `pip` and plan to use cloud services as remote
-> storage, you might need to install these optional dependencies: `[s3]`,
-> `[azure]`, `[gdrive]`, `[gs]`, `[oss]`, `[ssh]`. Alternatively, use `[all]` to
-> include them all. The command should look like this: `pip install "dvc[s3]"`.
-> (This example installs `boto3` library along with DVC to support S3 storage.)
+</admon>
 
-## Options
+## Command options/flags
 
 - `--system` - save remote configuration to the system config file (e.g.
   `/etc/xdg/dvc/config`) instead of `.dvc/config`.

diff --git a/content/docs/command-reference/remote/default.md b/content/docs/command-reference/remote/default.md
@@ -1,7 +1,6 @@
 # remote default
 
-Set/unset the default
-[remote storage](/doc/user-guide/data-management/remote-storage).
+Set/unset the default `dvc remote`.
 
 ## Synopsis
 

diff --git a/content/docs/command-reference/remote/index.md b/content/docs/command-reference/remote/index.md
@@ -26,49 +26,22 @@ positional arguments:
 
 ## Description
 
-What is data remote?
+DVC remotes are distributed storage locations for your data sets and ML models
+(similar to Git remotes, but for <abbr>cached</abbr> assets). This optional
+feature is typically used to share or back up copies of all or some of your
+data. Several types are supported: Amazon S3, Google Drive, SSH, HTTP, local
+file systems, among others.
 
-The same way as GitHub provides storage hosting for Git repositories, DVC
-remotes provide a location to store and share data and models. You can pull data
-assets created by colleagues from DVC remotes without spending time and
-resources to build or process them locally. Remote storage can also save space
-on your local environment – DVC can [fetch](/doc/command-reference/fetch) into
-the <abbr>cache directory</abbr> only the data you need for a specific
-branch/commit.
+<admon icon="book">
 
-Using DVC with remote storage is optional. DVC commands use the local cache
-(usually in dir `.dvc/cache`) as data storage by default. This enables the main
-DVC usage scenarios out of the box.
-
-DVC supports several types of remote storage: local file system, SSH, Amazon S3,
-Google Cloud Storage, HTTP, HDFS, among others. Refer to `dvc remote add` for
-more details.
-
-<admon type="info">
-
-If you installed DVC via `pip` and plan to use cloud services as remote storage,
-you might need to install these optional dependencies: `[s3]`, `[azure]`,
-`[gdrive]`, `[gs]`, `[oss]`, `[ssh]`. Alternatively, use `[all]` to include them
-all. The command should look like this: `pip install "dvc[s3]"`. (This example
-installs `boto3` library along with DVC to support S3 storage.)
-
-</admon>
-
-### Managing remote storage
-
-<admon type="info">
-
-For an intro on DVC remote usage see [Storing and sharing data].
-
-[storing and sharing data]:
-  /doc/start/data-management/data-versioning#storing-and-sharing
+Learn more about [remote storage].
 
 </admon>
 
-`dvc remote` subcommands read or modify DVC [config files], where DVC remotes
-are set up. Alternatively, `dvc config` can be used, or the config files can be
-edited manually.
+`dvc remote` subcommands read or modify DVC [config files] (`.dvc/config` by
+default). Alternatively, the config files can be edited manually.
 
+[types of storage]: /doc/command-reference/remote/add#supported-storage-types
 [config files]: /doc/command-reference/config
 
 ## Options
@@ -88,8 +61,8 @@ edited manually.
 
 While the term may seem contradictory, it doesn't have to be. The "local" part
 refers to the type of location where the storage is: another directory in the
-same file system. "Remote" is how we call storage for <abbr>DVC projects</abbr>.
-It's essentially a local backup for data tracked by DVC.
+same file system. "Remote" is what we call storage for <abbr>DVC
+projects</abbr>. It's essentially a local backup for data tracked by DVC.
 
 </details>
 

diff --git a/content/docs/command-reference/remote/list.md b/content/docs/command-reference/remote/list.md
@@ -1,7 +1,6 @@
 # remote list
 
-List all available
-[DVC remotes](/doc/user-guide/data-management/remote-storage).
+List all `dvc remote` names and locations.
 
 ## Synopsis
 
@@ -12,9 +11,11 @@ usage: dvc remote list [-h] [--global | --system | --project | --local]
 
 ## Description
 
-Reads DVC configuration files and prints the list of available remotes,
-including names and URLs. Remotes are read from the system, global, project, and
-local config files (in that order).
+Reads [DVC configuration] and prints the list of available remotes, including
+their names and URLs/paths. Remotes are read from the system, global, project,
+and local config files (in that order).
+
+[dvc configuration]: /doc/command-reference/config#remote
 
 ## Options
 

diff --git a/content/docs/command-reference/remote/modify.md b/content/docs/command-reference/remote/modify.md
@@ -1,12 +1,14 @@
 # remote modify
 
-Configure a [DVC remote](/doc/user-guide/data-management/remote-storage).
+Configure an existing `dvc remote`.
 
 <admon type="tip">
 
-This command is commonly needed after `dvc remote add` or `dvc remote default`
-to set up credentials or for other customizations specific to the
-[storage type](#available-parameters-per-storage-type).
+This command is commonly needed after `dvc remote add` to set up credentials or
+other customizations. See [Remote storage configuration] for more information.
+
+[remote storage configuration]:
+  /doc/user-guide/data-management/remote-storage#configuration
 
 </admon>
 
@@ -25,16 +27,43 @@ positional arguments:
 
 ## Description
 
-Remote `name` and `option` name are required. Config option names are specific
-to the remote type. See `dvc remote add` and
-[Available parameters](#available-parameters-per-storage-type) below for a list
-of remote storage types.
+The DVC remote's `name` and a valid `option` to modify are required. Remote
+options or [config parameters](#available-parameters-per-storage-type) are
+specific to the storage type and typically require a `value` as well.
+
+This command updates a [`remote`] section in the [config file] (`.dvc/config`):
+
+```cli
+$ dvc remote modify temp url /mnt/c/tmp/dvcstore
+```
+
+```git
+# .dvc/config
+['remote "temp"']
+-     url = /tmp/dvcstore
++     url = /mnt/c/tmp/dvcstore
+```
+
+<admon type="info">
+
+If you [installed DVC] via `pip` and plan to use cloud services as remote
+storage, you might need to install these optional dependencies: `[s3]`,
+`[azure]`, `[gdrive]`, `[gs]`, `[oss]`, `[ssh]`. Use `[all]` to include them
+all. For example:
+
+```cli
+$ pip install "dvc[s3]"
+```
+
+[installed dvc]: /doc/install
+
+</admon>
 
-This command modifies a `remote` section in the project's
-[config file](/doc/command-reference/config). Alternatively, `dvc config` or
-manual editing could be used to change the configuration.
+[config file]: /doc/command-reference/config
+[`remote`]: /doc/command-reference/config#remote
+[`core`]: /doc/command-reference/config#core
 
-## Command options (flags)
+## Command options/flags
 
 - `-u`, `--unset` - remove the configuration `option` from a config file. Don't
   provide a `value` argument when employing this flag.

diff --git a/content/docs/command-reference/remote/remove.md b/content/docs/command-reference/remote/remove.md
@@ -1,6 +1,6 @@
 # remote remove
 
-Remove a [DVC remote](/doc/user-guide/data-management/remote-storage).
+Remove a `dvc remote`.
 
 <admon type="info">
 

diff --git a/content/docs/command-reference/remote/rename.md b/content/docs/command-reference/remote/rename.md
@@ -1,6 +1,6 @@
 # remote rename
 
-Rename a [DVC remote](/doc/user-guide/data-management/remote-storage).
+Rename a `dvc remote`.
 
 <admon type="info">
 

diff --git a/content/docs/install/linux.md b/content/docs/install/linux.md
@@ -29,10 +29,11 @@ Note that Python 3.8+ is needed to get the latest version of DVC.
 $ pip install dvc
 ```
 
-Depending on the type of the [remote storage](/doc/command-reference/remote) you
-plan to use, you might need to install optional dependencies: `[s3]`,
-`[gdrive]`, `[gs]`, `[azure]`, `[ssh]`, `[hdfs]`, `[webdav]`, `[oss]`. Use
-`[all]` to include them all.
+Depending on the type of the [remote storage] you plan to use, you might need to
+install optional dependencies: `[s3]`, `[gdrive]`, `[gs]`, `[azure]`, `[ssh]`,
+`[hdfs]`, `[webdav]`, `[oss]`. Use `[all]` to include them all.
+
+[remote storage]: /doc/user-guide/data-management/remote-storage
 
 <details id="example-pip-with-support-for-amazon-s3-storage">
 
@@ -65,9 +66,9 @@ $ conda install -c conda-forge mamba # installs much faster than conda
 $ mamba install -c conda-forge dvc
 ```
 
-Depending on the type of the [remote storage](/doc/command-reference/remote) you
-plan to use, you might need to install optional dependencies: `dvc-s3`,
-`dvc-azure`, `dvc-gdrive`, `dvc-gs`, `dvc-oss`, `dvc-ssh`.
+Depending on the type of the [remote storage] you plan to use, you might need to
+install optional dependencies: `dvc-s3`, `dvc-azure`, `dvc-gdrive`, `dvc-gs`,
+`dvc-oss`, `dvc-ssh`.
 
 <details id="example-conda-with-support-for-amazon-s3-storage">
 

diff --git a/content/docs/install/macos.md b/content/docs/install/macos.md
@@ -59,10 +59,11 @@ Note that Python 3.8+ is needed to get the latest version of DVC.
 $ pip install dvc
 ```
 
-Depending on the type of the [remote storage](/doc/command-reference/remote) you
-plan to use, you might need to install optional dependencies: `[s3]`,
-`[gdrive]`, `[gs]`, `[azure]`, `[ssh]`, `[hdfs]`, `[webdav]`, `[oss]`. Use
-`[all]` to include them all.
+Depending on the type of the [remote storage] you plan to use, you might need to
+install optional dependencies: `[s3]`, `[gdrive]`, `[gs]`, `[azure]`, `[ssh]`,
+`[hdfs]`, `[webdav]`, `[oss]`. Use `[all]` to include them all.
+
+[remote storage]: /doc/user-guide/data-management/remote-storage
 
 <details id="example-pip-with-support-for-amazon-s3-storage">
 
@@ -90,9 +91,9 @@ $ conda install -c conda-forge mamba # installs much faster than conda
 $ mamba install -c conda-forge dvc
 ```
 
-Depending on the type of the [remote storage](/doc/command-reference/remote) you
-plan to use, you might need to install optional dependencies: `dvc-s3`,
-`dvc-azure`, `dvc-gdrive`, `dvc-gs`, `dvc-oss`, `dvc-ssh`.
+Depending on the type of the [remote storage] you plan to use, you might need to
+install optional dependencies: `dvc-s3`, `dvc-azure`, `dvc-gdrive`, `dvc-gs`,
+`dvc-oss`, `dvc-ssh`.
 
 <details id="example-conda-with-support-for-amazon-s3-storage">
 

diff --git a/content/docs/install/windows.md b/content/docs/install/windows.md
@@ -43,9 +43,11 @@ $ conda install -c conda-forge mamba # installs much faster than conda
 $ mamba install -c conda-forge dvc
 ```
 
-Depending on the type of the [remote storage](/doc/command-reference/remote) you
-plan to use, you might need to install optional dependencies: `dvc-s3`,
-`dvc-azure`, `dvc-gdrive`, `dvc-gs`, `dvc-oss`, `dvc-ssh`.
+Depending on the type of the [remote storage] you plan to use, you might need to
+install optional dependencies: `dvc-s3`, `dvc-azure`, `dvc-gdrive`, `dvc-gs`,
+`dvc-oss`, `dvc-ssh`.
+
+[remote storage]: /doc/user-guide/data-management/remote-storage
 
 <details id="example-conda-with-support-for-amazon-s3-storage">
 
@@ -82,9 +84,9 @@ Note that Python 3.8+ is needed to get the latest version of DVC.
 $ pip install dvc
 ```
 
-Depending on the type of the [remote storage](/doc/command-reference/remote) you
-plan to use, you might need to install optional dependencies: `[s3]`, `[azure]`,
-`[gdrive]`, `[gs]`, `[oss]`, `[ssh]`. Use `[all]` to include them all.
+Depending on the type of the [remote storage] you plan to use, you might need to
+install optional dependencies: `[s3]`, `[azure]`, `[gdrive]`, `[gs]`, `[oss]`,
+`[ssh]`. Use `[all]` to include them all.
 
 <details id="example-pip-with-support-for-amazon-s3-storage">