regular update to docs (early June)

static/docs/commands-reference/cache_dir.md

@@ -33,7 +33,8 @@ file, as they are expected in the config file.
   specify private config options in your config, that you don't want to track
   and share through Git.
 
-- `-u`, `--unset` - remove a specified config option from a config file.
+- `-u`, `--unset` - remove the `cache.dir` config option from the config file.
+  Don't provide a `value` when using this flag.
 
 - `-h`, `--help` - prints the usage/help message, and exit.
 

static/docs/commands-reference/config.md

@@ -15,7 +15,7 @@ positional arguments:
 
 You can query/set/replace/unset DVC configuration options with this command. It
 takes a config option `name` (a section and a key, separated by a dot) and its
-`value`.
+`value` (any valid alpha-numeric string generally).
 
 This command reads and overwrites the DVC config file `.dvc/config`. If
 `--local` option is specified, `.dvc/config.local` is modified instead.

static/docs/commands-reference/remote_add.md

@@ -1,8 +1,9 @@
 # remote add
 
-Add a new data remote. Depending on your storage type you might need to run
-`dvc remote modify` to provide credentials and/or configure other remote
-parameters.
+Add a new data remote.
+
+> Depending on your storage type, you may also need `dvc remote modify` to
+> provide credentials and/or configure other remote parameters.
 
 See also [default](/doc/commands-reference/remote-default),
 [list](/doc/commands-reference/remote-list),
@@ -76,6 +77,8 @@ Use `dvc config` to unset/change the default remote as so:
 
 - `-f`, `--force` - to overwrite existing remote with new `url` value.
 
+## Examples
+
 <details>
 
 ### Click for a local remote example
@@ -309,9 +312,9 @@ $ export OSS_ACCESS_KEY_SECRET='AccessKeySecret'
 
 </details>
 
-## Examples
+## Examples: Custom configuration of an S3 remote
 
-Add AWS S3 _default_ (via `-d` option) remote and modify its region:
+Add a AWS S3 remote as the _default_ (via `-d` option), and modify its region:
 
 ```dvc
 $ dvc remote add -d myremote s3://mybucket/myproject
@@ -320,7 +323,7 @@ Setting 'myremote' as a default remote.
 $ dvc remote modify myremote region us-east-2
 ```
 
-DVC config file would look like (run `cat .dvc/config`):
+DVC config file (`.dvc/config`) now looks like this:
 
 ```ini
 ['remote "myremote"']
@@ -330,21 +333,21 @@ region = us-east-2
 remote = myremote
 ```
 
-And list of remotes like this:
+The list of remotes should now be:
 
 ```dvc
 $ dvc remote list
 
 myremote	s3://mybucket/myproject
 ```
 
-You can overwrite existing remote using `-f` with `dvc remote add` as under:
+You can overwrite existing remotes using `-f` with `dvc remote add`:
 
 ```dvc
 $ dvc remote add -f myremote s3://mybucket/mynewproject
 ```
 
-List remotes to view the updated remote:
+List remotes again to view the updated remote:
 
 ```dvc
 $ dvc remote list

static/docs/commands-reference/remote_default.md

@@ -1,8 +1,9 @@
 # remote default
 
-To set/unset default data remote. Depending on your storage type you may need to
-run `dvc remote modify` to provide credentials and/or configure other remote
-parameters.
+Set/unset a default data remote.
+
+> Depending on your storage type, you may also need `dvc remote modify` to
+> provide credentials and/or configure other remote parameters.
 
 See also [add](/doc/commands-reference/remote-add),
 [list](/doc/commands-reference/remote-list),

static/docs/commands-reference/remote_modify.md

@@ -2,6 +2,10 @@
 
 Modify remote settings.
 
+> This command is commonly needed after `dvc remote add` or
+> [default](/doc/commands-reference/remote-default) to setup credentials or
+> other customizations to each remote type.
+
 See also [add](/doc/commands-reference/remote-add),
 [default](/doc/commands-reference/remote-default),
 [list](/doc/commands-reference/remote-list), and
@@ -10,9 +14,8 @@ See also [add](/doc/commands-reference/remote-add),
 ## Synopsis
 
 ```usage
-usage: dvc remote modify [-h] [-q | -v] [-u]
-                       [--global] [--system] [--local]
-                       name option [value]
+usage: dvc remote modify [-h] [--global] [--system] [--local] [-q | -v]
+                         [-u] name option [value]
 
 positional arguments:
  name           Name of the remote
@@ -26,13 +29,14 @@ Remote `name` and `option` name are required. Option names are remote type
 specific. See below examples and a list of per remote type - AWS S3, Google
 cloud, Azure, SSH, ALiyun OSS, and others.
 
-This command modifies a section in the DVC
+This command modifies a `remote` section in the DVC
 [config file](/doc/user-guide/dvc-files-and-directories). Alternatively,
 `dvc config` or manual editing could be used to change settings.
 
 ## Options
 
-- `-u`, `--unset` - delete configuration value
+- `-u`, `--unset` - delete configuration value for given `option`. Don't provide
+  a `value` when using this flag.
 
 - `--global` - save remote configuration to the global config (e.g.
   `~/.config/dvc/config`) instead of `.dvc/config`.
@@ -46,6 +50,8 @@ This command modifies a section in the DVC
   config, that you don't want to track and share through Git (credentials,
   private locations, etc).
 
+## Examples
+
 <details>
 
 ### Click for AWS S3 available options
@@ -252,7 +258,7 @@ $ dvc remote modify myremote oss_endpoint endpoint
 
 </details>
 
-## Examples
+## Examples: Customize an S3 remote
 
 Let's first set up a _default_ S3 remote:
 

static/docs/commands-reference/remote_remove.md

@@ -1,7 +1,7 @@
 # remote remove
 
 Remove a specified remote. This command affects DVC configuration files only, it
-does not physically remove your data files stored remotely.
+does not physically remove data files stored remotely.
 
 See also [add](/doc/commands-reference/remote-add),
 [default](/doc/commands-reference/remote-default),