From 1c288cab9ee2c895b1ef8dca2f358d17e455a61c Mon Sep 17 00:00:00 2001
From: Jorge Orpinel <jorge@orpinel.com>
Date: Thu, 9 Jan 2020 13:13:39 -0600
Subject: [PATCH 01/23] web: simplify query and hash removal from path for docs
 engine per
 https://github.com/iterative/dvc.org/commit/06f1071debbc296175d815d4371e88e1ceb7c43a#commitcomment-36732551

---
 pages/doc.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pages/doc.js b/pages/doc.js
index 91c5d18d34..f9ac02708e 100644
--- a/pages/doc.js
+++ b/pages/doc.js
@@ -127,7 +127,7 @@ export default function Documentation({ item, headings, markdown, errorCode }) {
 }
 
 Documentation.getInitialProps = async ({ asPath, req }) => {
-  const item = getItemByPath(asPath.split('#')[0].split('?')[0])
+  const item = getItemByPath(asPath.split(/[?#]/)[0])
 
   if (!item) {
     return {

From 16a26c987fa25d0762622dfcbb8a96c537779606 Mon Sep 17 00:00:00 2001
From: Jorge Orpinel <jorge@orpinel.com>
Date: Thu, 9 Jan 2020 13:44:45 -0600
Subject: [PATCH 02/23] cmd ref: improve `path` description in get and import

---
 public/static/docs/command-reference/get.md    | 6 +++---
 public/static/docs/command-reference/import.md | 6 +++---
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/public/static/docs/command-reference/get.md b/public/static/docs/command-reference/get.md
index f8b4c693d7..77291d94d7 100644
--- a/public/static/docs/command-reference/get.md
+++ b/public/static/docs/command-reference/get.md
@@ -35,9 +35,9 @@ doesn't have a default remote set up, instead of downloading, DVC will try to
 copy the target data from the external source project or its
 <abbr>cache</abbr>).
 
-The `path` argument of this command is used to specify the location, within the
-source repository at `url`, of the target(s) to be downloaded. It can point to
-any file or directory in the source project, including <abbr>outputs</abbr>
+The `path` argument of this command is used to specify the location of the
+target(s) to be downloaded within the source repository at `url`. It can point
+to any file or directory in the source project, including <abbr>outputs</abbr>
 tracked by DVC as well as files tracked by Git. Note that for the former, data
 should be specified in one of the [DVC-files](/doc/user-guide/dvc-file-format)
 of the source repository. (In this case, a default
diff --git a/public/static/docs/command-reference/import.md b/public/static/docs/command-reference/import.md
index b63fc18b9d..04a49e2498 100644
--- a/public/static/docs/command-reference/import.md
+++ b/public/static/docs/command-reference/import.md
@@ -35,9 +35,9 @@ doesn't have a default remote set up, instead of downloading, DVC will try to
 copy the target data from the external source project or its
 <abbr>cache</abbr>).
 
-The `path` argument of this command is used to specify the location, within the
-source repository at `url`, of the target(s) to be downloaded. It can point to
-any file or directory in the source project, including <abbr>outputs</abbr>
+The `path` argument of this command is used to specify the location of the
+target(s) to be downloaded within the source repository at `url`. It can point
+to any file or directory in the source project, including <abbr>outputs</abbr>
 tracked by DVC as well as files tracked by Git. Note that for the former, data
 should be specified in one of the [DVC-files](/doc/user-guide/dvc-file-format)
 of the source repository. (In this case, a default

From 26d9928b1b7b4751255f282a526a925d9961d8bf Mon Sep 17 00:00:00 2001
From: Jorge Orpinel <jorge@orpinel.com>
Date: Sat, 11 Jan 2020 21:00:04 -0600
Subject: [PATCH 03/23] docs: remove all H4s and other improvements near the
 changed text per
 https://github.com/iterative/dvc.org/pull/914#pullrequestreview-341551048

---
 .../docs/command-reference/remote/add.md      | 42 +++++++------------
 .../static/docs/command-reference/version.md  |  4 +-
 2 files changed, 17 insertions(+), 29 deletions(-)

diff --git a/public/static/docs/command-reference/remote/add.md b/public/static/docs/command-reference/remote/add.md
index 3bee64de95..9987c75579 100644
--- a/public/static/docs/command-reference/remote/add.md
+++ b/public/static/docs/command-reference/remote/add.md
@@ -217,28 +217,22 @@ $ dvc remote modify myremote gdrive_client_id my_gdrive_client_id
 $ dvc remote modify myremote gdrive_client_secret gdrive_client_secret
 ```
 
-On first usage of remote you will be prompted to visit access token generation
-link in browser. It will ask you to log into Google account associated with
-Google Drive, which you want to use as DVC's remote. Login process will guide
-you through granting Google Drive access permissions to the used Google Project.
+On first usage of the remote you will be prompted to visit an access token
+generation URL via browser. It will ask you to log into the Google account
+associated with the Google Drive you want to use as remote. The login process
+will guide you through the granting of the required access permissions.
 
-On successful access token generation, token data will be cached in git ignored
-directory with path `.dvc/tmp/gdrive-user-credentials.json`. Do not share token
-data with anyone else to prevent unauthorized access to your Google Drive.
+On successful access token generation, the token data will be cached in a
+Git-ignored directory (located in `.dvc/tmp/gdrive-user-credentials.json`).
 
-#### Shared drives support
+> 💡 Do not share the token data with anyone else to prevent unauthorized access
+> to your Google Drive.
 
-You need to obtain `id` of your shared drive directory to use it as part of URL
-passed to DVC. `id` can be found in your web browser address bar when shared
-drive is opened. For example, for the URL
-
-```dvc
-https://drive.google.com/drive/folders/0AIac4JZqHhKmUk9PDA
-```
-
-the `id` will be equal to `0AIac4JZqHhKmUk9PDA`.
-
-Use obtained `id` in remote's URL:
+For **shared drives**, you need to obtain the directory ID and use it as part of
+URL passed to DVC. This ID can be found in your web browser address bar when the
+shared drive is opened. For example, for the URL
+`https://drive.google.com/drive/folders/0AIac4JZqHhKmUk9PDA`, use
+`0AIac4JZqHhKmUk9PDA` as ID:
 
 ```dvc
 $ dvc remote add myremote gdrive://0AIac4JZqHhKmUk9PDA/my-dvc-root
@@ -287,19 +281,13 @@ $ export OSS_ACCESS_KEY_SECRET="my-key-secret"
 $ export OSS_ENDPOINT="endpoint"
 ```
 
-#### Test your OSS storage using docker
-
-Start a container running an OSS emulator.
+To **test your OSS storage using docker**, start a container running an OSS
+emulator, and setup the environment variables, for example:
 
 ```dvc
 $ git clone https://github.com/nanaya-tachibana/oss-emulator.git
 $ docker image build -t oss:1.0 oss-emulator
 $ docker run --detach -p 8880:8880 --name oss-emulator oss:1.0
-```
-
-Setup environment variables.
-
-```dvc
 $ export OSS_BUCKET='my-bucket'
 $ export OSS_ENDPOINT='localhost:8880'
 $ export OSS_ACCESS_KEY_ID='AccessKeyID'
diff --git a/public/static/docs/command-reference/version.md b/public/static/docs/command-reference/version.md
index 5f6d839053..b1f3c8fabe 100644
--- a/public/static/docs/command-reference/version.md
+++ b/public/static/docs/command-reference/version.md
@@ -34,7 +34,7 @@ system/environment:
 > report file system information. Please see the original
 > [issue on GitHub](https://github.com/iterative/dvc/issues/2284) for more info.
 
-#### Components of DVC version
+### Components of DVC version
 
 The detail of DVC version depends upon the way of installing DVC.
 
@@ -58,7 +58,7 @@ The detail of DVC version depends upon the way of installing DVC.
   following part is the latest `master` branch commit hash. The optional suffix
   `.mod` means that code is modified.
 
-#### What we mean by "Binary"
+### What we mean by "Binary"
 
 The detail of `Binary` depends on the way DVC was downloaded and
 [installed](/doc/install).

From 3450ff623abbd4ff50fe5f7319cc8560cd09d271 Mon Sep 17 00:00:00 2001
From: Jorge Orpinel <jorge@orpinel.com>
Date: Sun, 12 Jan 2020 13:13:50 -0600
Subject: [PATCH 04/23] doc: capitalize all examples

---
 public/static/docs/command-reference/import.md         | 2 +-
 public/static/docs/command-reference/remote/index.md   | 2 +-
 public/static/docs/user-guide/external-dependencies.md | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/public/static/docs/command-reference/import.md b/public/static/docs/command-reference/import.md
index 04a49e2498..7004517b32 100644
--- a/public/static/docs/command-reference/import.md
+++ b/public/static/docs/command-reference/import.md
@@ -129,7 +129,7 @@ Several of the values above are pulled from the original stage file
 subfields under `repo` are used to save the origin and version of the
 dependency.
 
-## Example: fixed revisions & re-importing
+## Example: Fixed revisions & re-importing
 
 To import a specific revision of a <abbr>data artifact</abbr>, we may use the
 `--rev` option:
diff --git a/public/static/docs/command-reference/remote/index.md b/public/static/docs/command-reference/remote/index.md
index 7e018cd6e7..04a461fbe3 100644
--- a/public/static/docs/command-reference/remote/index.md
+++ b/public/static/docs/command-reference/remote/index.md
@@ -105,7 +105,7 @@ $ dvc remote add -d mynewremote s3://mybucket/myproject
 $ dvc remote modify mynewremote region us-east-2
 ```
 
-## Example: Remove remote:
+## Example: Remove remote
 
 ```dvc
 $ dvc remote remove mynewremote
diff --git a/public/static/docs/user-guide/external-dependencies.md b/public/static/docs/user-guide/external-dependencies.md
index 5930a8995b..b8620a037b 100644
--- a/public/static/docs/user-guide/external-dependencies.md
+++ b/public/static/docs/user-guide/external-dependencies.md
@@ -110,7 +110,7 @@ $ dvc run -d remote://example/data.txt \
 Please refer to `dvc remote add` for more details like setting up access
 credentials for the different remotes.
 
-## Example: import-url command
+## Example: `import-url` command
 
 In the previous examples, downloading commands were used: `aws s3 cp`, `scp`,
 `wget`, etc. `dvc import-url` simplifies the downloading for all the supported

From 00f47519308922294d558bc5f7479a1f9560a9df Mon Sep 17 00:00:00 2001
From: Jorge Orpinel <jorge@orpinel.com>
Date: Sun, 12 Jan 2020 13:30:12 -0600
Subject: [PATCH 05/23] remote: improve index examples per
 https://github.com/iterative/dvc.org/pull/902#issuecomment-573446787

---
 .../docs/command-reference/remote/index.md    | 28 +++++++++++++++----
 1 file changed, 23 insertions(+), 5 deletions(-)

diff --git a/public/static/docs/command-reference/remote/index.md b/public/static/docs/command-reference/remote/index.md
index 04a461fbe3..3c35c3f3e7 100644
--- a/public/static/docs/command-reference/remote/index.md
+++ b/public/static/docs/command-reference/remote/index.md
@@ -82,8 +82,6 @@ project/repository itself. Read "local, but external" storage.
 
 ```dvc
 $ dvc remote add -d myremote /path/to/remote
-$ dvc remote list
-myremote        /path/to/remote
 ```
 
 The <abbr>project</abbr>'s config file should now look like this:
@@ -95,17 +93,37 @@ url = /path/to/remote
 remote = myremote
 ```
 
-## Example: Add a default Amazon S3 remote and modify its region
+## Example: Add an Amazon S3 remote and modify its region
 
 > 💡 Before adding an S3 remote, be sure to
 > [Create a Bucket](https://docs.aws.amazon.com/AmazonS3/latest/gsg/CreatingABucket.html).
 
 ```dvc
-$ dvc remote add -d mynewremote s3://mybucket/myproject
+$ dvc remote add mynewremote s3://mybucket/myproject
 $ dvc remote modify mynewremote region us-east-2
 ```
 
-## Example: Remove remote
+The project's config file should now look something like this:
+
+```ini
+['remote "myremote"']
+url = /path/to/remote
+[core]
+remote = myremote
+['remote "mynewremote"']
+url = s3://mybucket/myproject
+region = us-east-2
+```
+
+## Example: List all remotes in the project
+
+```dvc
+$ dvc remote list
+myremote	/path/to/remote
+mynewremote	s3://mybucket/myproject
+```
+
+## Example: Remove a remote
 
 ```dvc
 $ dvc remote remove mynewremote

From 8b1c720d3edd4c5e4460f644511d465111943485 Mon Sep 17 00:00:00 2001
From: Jorge Orpinel <jorge@orpinel.com>
Date: Sun, 12 Jan 2020 13:32:35 -0600
Subject: [PATCH 06/23] Add note about --default in remote index example

---
 public/static/docs/command-reference/remote/index.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/public/static/docs/command-reference/remote/index.md b/public/static/docs/command-reference/remote/index.md
index 3c35c3f3e7..a0ded7d708 100644
--- a/public/static/docs/command-reference/remote/index.md
+++ b/public/static/docs/command-reference/remote/index.md
@@ -80,6 +80,8 @@ project/repository itself. Read "local, but external" storage.
 
 </details>
 
+We use the `-d` (`--default`) option of `dvc remote add` for this:
+
 ```dvc
 $ dvc remote add -d myremote /path/to/remote
 ```

From 371400b5f9ac6a23729c2b5ecd4376fc9073d33e Mon Sep 17 00:00:00 2001
From: Jorge Orpinel <jorge@orpinel.com>
Date: Sun, 12 Jan 2020 14:10:14 -0600
Subject: [PATCH 07/23] remote: reinstated bold "headers" inside expandable
 sections of add per
 https://github.com/iterative/dvc.org/pull/915#pullrequestreview-341551692 and
 https://github.com/iterative/dvc.org/pull/915#pullrequestreview-341551720

---
 public/static/docs/command-reference/remote/add.md | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/public/static/docs/command-reference/remote/add.md b/public/static/docs/command-reference/remote/add.md
index 9987c75579..1d758dd87e 100644
--- a/public/static/docs/command-reference/remote/add.md
+++ b/public/static/docs/command-reference/remote/add.md
@@ -228,9 +228,11 @@ Git-ignored directory (located in `.dvc/tmp/gdrive-user-credentials.json`).
 > 💡 Do not share the token data with anyone else to prevent unauthorized access
 > to your Google Drive.
 
-For **shared drives**, you need to obtain the directory ID and use it as part of
-URL passed to DVC. This ID can be found in your web browser address bar when the
-shared drive is opened. For example, for the URL
+**Support for shared drives**
+
+For this, you need to obtain the directory ID and use it as part of URL passed
+to DVC. This ID can be found in your web browser address bar when the shared
+drive is opened. For example, for the URL
 `https://drive.google.com/drive/folders/0AIac4JZqHhKmUk9PDA`, use
 `0AIac4JZqHhKmUk9PDA` as ID:
 
@@ -281,8 +283,10 @@ $ export OSS_ACCESS_KEY_SECRET="my-key-secret"
 $ export OSS_ENDPOINT="endpoint"
 ```
 
-To **test your OSS storage using docker**, start a container running an OSS
-emulator, and setup the environment variables, for example:
+**Testing your OSS storage using docker**
+
+Start a container running an OSS emulator, and setup the environment variables,
+for example:
 
 ```dvc
 $ git clone https://github.com/nanaya-tachibana/oss-emulator.git

From 6309a56362542bfc287d71fc178915448eb92d07 Mon Sep 17 00:00:00 2001
From: Jorge Orpinel <jorge@orpinel.com>
Date: Mon, 13 Jan 2020 15:28:45 -0600
Subject: [PATCH 08/23] user-guide: remove unnecessary note from core contrib
 guide

---
 public/static/docs/user-guide/contributing/core.md | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/public/static/docs/user-guide/contributing/core.md b/public/static/docs/user-guide/contributing/core.md
index b5bbebfd7b..381a06f15d 100644
--- a/public/static/docs/user-guide/contributing/core.md
+++ b/public/static/docs/user-guide/contributing/core.md
@@ -57,10 +57,6 @@ $ source .env/bin/activate
 $ pip install -e ".[all,tests]"
 ```
 
-> Note that the double quotes (`""`) used to wrap the dependencies to be
-> installed are only compulsory when using `zsh`. In `bash`, installation
-> commands can work without them: `pip install -e .[all,tests]`.
-
 Install coding style pre-commit hooks with:
 
 ```dvc

From c88d436e55f85d9a3cb269884cdfe26bf6fad8be Mon Sep 17 00:00:00 2001
From: Jorge Orpinel <jorge@orpinel.com>
Date: Mon, 13 Jan 2020 16:25:43 -0600
Subject: [PATCH 09/23] cmd ref: review language around term "effect"
 (conditional applicability of options)

---
 public/static/docs/command-reference/add.md   | 12 +++++------
 .../static/docs/command-reference/checkout.md | 20 +++++++++----------
 .../static/docs/command-reference/commit.md   | 19 +++++++++---------
 .../static/docs/command-reference/config.md   |  4 ++--
 public/static/docs/command-reference/fetch.md | 19 +++++++++---------
 public/static/docs/command-reference/get.md   |  3 ++-
 .../static/docs/command-reference/import.md   | 13 +++++++-----
 .../docs/command-reference/metrics/show.md    |  7 ++++---
 public/static/docs/command-reference/pull.md  | 18 ++++++++---------
 public/static/docs/command-reference/push.md  | 18 ++++++++---------
 public/static/docs/command-reference/repro.md |  4 ++--
 public/static/docs/command-reference/run.md   |  4 ++--
 .../static/docs/command-reference/status.md   | 12 +++++------
 13 files changed, 78 insertions(+), 75 deletions(-)

diff --git a/public/static/docs/command-reference/add.md b/public/static/docs/command-reference/add.md
index 82b728653a..0e992c116d 100644
--- a/public/static/docs/command-reference/add.md
+++ b/public/static/docs/command-reference/add.md
@@ -87,10 +87,10 @@ reproducible.
 
 ## Options
 
-- `-R`, `--recursive` - `targets` is expected to contain at least one directory
-  path for this option to have effect. Determines the files to add by searching
-  each target directory and its subdirectories for data files. For each file
-  found, a new DVC-file is created using the process described in this command's
+- `-R`, `--recursive` - `targets` is expected to contain one or more directories
+  for this option to have effect. Determines the files to add by searching each
+  target directory and its subdirectories for data files. For each file found, a
+  new DVC-file is created using the process described in this command's
   description.
 
 - `--no-commit` - do not save outputs to cache. A DVC-file is created, and an
@@ -197,8 +197,8 @@ Saving information to 'pics.dvc'.
 
 There are no [DVC-files](/doc/user-guide/dvc-file-format) generated within this
 directory structure, but the images are all added to the <abbr>cache</abbr>. DVC
-prints a message to that effect, mentioning that `md5` values are computed for
-each directory. A single `pics.dvc` DVC-file is generated for the top-level
+prints a message about this, mentioning that `md5` values are computed for each
+directory. A single `pics.dvc` DVC-file is generated for the top-level
 directory, and it contains:
 
 ```yaml
diff --git a/public/static/docs/command-reference/checkout.md b/public/static/docs/command-reference/checkout.md
index 829f1b1602..5045082b5b 100644
--- a/public/static/docs/command-reference/checkout.md
+++ b/public/static/docs/command-reference/checkout.md
@@ -67,16 +67,16 @@ be pulled from remote storage using `dvc pull`.
 
 ## Options
 
-- `-d`, `--with-deps` - determine files to update by tracking dependencies to
-  the target DVC-files (stages). This option only has effect when one or more
-  `targets` are specified. By traversing all stage dependencies, DVC searches
-  backward from the target stages in the corresponding pipelines. This means DVC
-  will not checkout files referenced in later stages than the `targets`.
-
-- `-R`, `--recursive` - `targets` is expected to contain at least one directory
-  path for this option to have effect. Determines the files to checkout by
-  searching each target directory and its subdirectories for DVC-files to
-  inspect.
+- `-d`, `--with-deps` - one or more `targets` should be specified for this
+  option to have effect. Determines files to update by tracking dependencies to
+  the target DVC-files (stages). By traversing all stage dependencies, DVC
+  searches backward from the target stages in the corresponding pipelines. This
+  means DVC will not checkout files referenced in later stages than the
+  `targets`.
+
+- `-R`, `--recursive` - `targets` is expected to contain one or more directories
+  for this option to have effect. Determines the files to checkout by searching
+  each target directory and its subdirectories for DVC-files to inspect.
 
 - `-f`, `--force` - does not prompt when removing workspace files. Changing the
   current set of DVC-files with `git checkout` can result in the need for DVC to
diff --git a/public/static/docs/command-reference/commit.md b/public/static/docs/command-reference/commit.md
index 053d6af7ce..2535d40e43 100644
--- a/public/static/docs/command-reference/commit.md
+++ b/public/static/docs/command-reference/commit.md
@@ -68,16 +68,15 @@ reproducibility in those cases.
 
 ## Options
 
-- `-d`, `--with-deps` - determine files to commit by tracking dependencies to
-  the target DVC-files (stages). This option only has effect when one or more
-  `targets` are specified. By traversing all stage dependencies, DVC searches
-  backward from the target stages in the corresponding pipelines. This means DVC
-  will not commit files referenced in later stages than the `targets`.
-
-- `-R`, `--recursive` - `targets` is expected to contain at least one directory
-  path for this option to have effect. Determines the files to commit by
-  searching each target directory and its subdirectories for DVC-files to
-  inspect.
+- `-d`, `--with-deps` - one or more `targets` should be specified for this
+  option to have effect. Determines files to commit by tracking dependencies to
+  the target DVC-files (stages). By traversing all stage dependencies, DVC
+  searches backward from the target stages in the corresponding pipelines. This
+  means DVC will not commit files referenced in later stages than the `targets`.
+
+- `-R`, `--recursive` - `targets` is expected to contain one or more directories
+  for this option to have effect. Determines the files to commit by searching
+  each target directory and its subdirectories for DVC-files to inspect.
 
 - `-f`, `--force` - commit data even if checksums for dependencies or outputs
   did not change.
diff --git a/public/static/docs/command-reference/config.md b/public/static/docs/command-reference/config.md
index 59ee19a932..829157fb5e 100644
--- a/public/static/docs/command-reference/config.md
+++ b/public/static/docs/command-reference/config.md
@@ -110,8 +110,8 @@ for more details.) This section contains the following options:
   > directory into paths relative to the config file location.
 
 - `cache.protected` - make files under DVC control read-only. Possible values
-  are `true` or `false` (default). Run `dvc checkout` for the change to go into
-  effect.
+  are `true` or `false` (default). Run `dvc checkout` after setting changing the
+  value for this option for the change to go into effect.
 
   Due to the way DVC handles linking between the data files in the cache and
   their counterparts in the <abbr>workspace</abbr>, it's easy to accidentally
diff --git a/public/static/docs/command-reference/fetch.md b/public/static/docs/command-reference/fetch.md
index 9b50b6c910..41d27d692b 100644
--- a/public/static/docs/command-reference/fetch.md
+++ b/public/static/docs/command-reference/fetch.md
@@ -78,16 +78,15 @@ specified in DVC-files currently in the project are considered by `dvc fetch`
   `dvc config core.remote`). The argument `REMOTE` is a remote name defined
   using the `dvc remote` command.
 
-- `-d`, `--with-deps` - determine files to download by tracking dependencies to
-  the target DVC-files (stages). This option only has effect when one or more
-  `targets` are specified. By traversing all stage dependencies, DVC searches
-  backward from the target stages in the corresponding pipelines. This means DVC
-  will not fetch files referenced in later stages than the `targets`.
-
-- `-R`, `--recursive` - `targets` is expected to contain at least one directory
-  path for this option to have effect. Determines the files to fetch by
-  searching each target directory and its subdirectories for DVC-files to
-  inspect.
+- `-d`, `--with-deps` - one or more `targets` should be specified for this
+  option to have effect. Determines files to download by tracking dependencies
+  to the target DVC-files (stages). By traversing all stage dependencies, DVC
+  searches backward from the target stages in the corresponding pipelines. This
+  means DVC will not fetch files referenced in later stages than the `targets`.
+
+- `-R`, `--recursive` - `targets` is expected to contain one or more directories
+  for this option to have effect. Determines the files to fetch by searching
+  each target directory and its subdirectories for DVC-files to inspect.
 
 - `-j JOBS`, `--jobs JOBS` - number of threads to run simultaneously to handle
   the downloading of files from the remote. Using more jobs may improve the
diff --git a/public/static/docs/command-reference/get.md b/public/static/docs/command-reference/get.md
index 77291d94d7..f16c825184 100644
--- a/public/static/docs/command-reference/get.md
+++ b/public/static/docs/command-reference/get.md
@@ -58,7 +58,8 @@ name.
   an existing directory is specified, then the output will be placed inside of
   it.
 
-- `--rev` - specific
+- `--rev` - `url` is expected to represent a Git repository for this option to
+  have an effect. Specific
   [Git revision](https://git-scm.com/book/en/v2/Git-Internals-Git-References)
   (such as a branch name, a tag, or a commit hash) of the DVC repository to
   download the file or directory from. The tip of the default branch is used by
diff --git a/public/static/docs/command-reference/import.md b/public/static/docs/command-reference/import.md
index 7004517b32..ba6b3d57d5 100644
--- a/public/static/docs/command-reference/import.md
+++ b/public/static/docs/command-reference/import.md
@@ -74,13 +74,16 @@ data artifact from the source project.
   an existing directory is specified, then the output will be placed inside of
   it.
 
-- `--rev` - specific
-  [Git revision](https://git-scm.com/book/en/v2/Git-Internals-Git-References)
+- `--rev` - `url` is expected to represent a Git repository for this option to
+  have an effect. Specific
+  [Git-revision](https://git-scm.com/book/en/v2/Git-Internals-Git-References)
   (such as a branch name, a tag, or a commit hash) of the DVC repository to
   import the data from. The tip of the repository's default branch is used by
-  default when this option is not specified. Note that this adds a `rev` field
-  in the import stage that fixes it to this revision. This can impact the
-  behavior of `dvc update`. (See **re-importing** example below.)
+  default when this option is not specified.
+
+  > Note that this adds a `rev` field in the import stage that fixes it to this
+  > revision. This can impact the behavior of `dvc update`. (See
+  > **re-importing** example below.)
 
 - `-h`, `--help` - prints the usage/help message, and exit.
 
diff --git a/public/static/docs/command-reference/metrics/show.md b/public/static/docs/command-reference/metrics/show.md
index a41c783d2b..4b10e378fe 100644
--- a/public/static/docs/command-reference/metrics/show.md
+++ b/public/static/docs/command-reference/metrics/show.md
@@ -89,9 +89,10 @@ extension.)
   Similar to `-a` above. Note that both options can be combined, for example
   using the `-aT` flag.
 
-- `-R`, `--recursive` - `path` is expected to be a directory for this option to
-  have effect. Determines the metric files to show by searching each target
-  directory and its subdirectories for DVC-files to inspect.
+- `-R`, `--recursive` - `targets` is expected to contain one or more directories
+  for this option to have effect. Determines the metric files to show by
+  searching each target directory and its subdirectories for DVC-files to
+  inspect.
 
 - `-h`, `--help` - prints the usage/help message, and exit.
 
diff --git a/public/static/docs/command-reference/pull.md b/public/static/docs/command-reference/pull.md
index 482e82b69e..f4fecc309f 100644
--- a/public/static/docs/command-reference/pull.md
+++ b/public/static/docs/command-reference/pull.md
@@ -72,15 +72,15 @@ reflinks or hardlinks to put it in the workspace without copying. See
   to save different experiments or project checkpoints. Note that both options
   can be combined, for example using the `-aT` flag.
 
-- `-d`, `--with-deps` - determines files to download by tracking dependencies to
-  the target DVC-files (stages). This option only has effect when one or more
-  `targets` are specified. By traversing all stage dependencies, DVC searches
-  backward from the target stages in the corresponding pipelines. This means DVC
-  will not pull files referenced in later stages than the `targets`.
-
-- `-R`, `--recursive` - `targets` is expected to contain at least one directory
-  path for this option to have effect. Determines the files to pull by searching
-  each target directory and its subdirectories for DVC-files to inspect.
+- `-d`, `--with-deps` - one or more `targets` should be specified for this
+  option to have effect. Determines files to download by tracking dependencies
+  to the target DVC-files (stages). By traversing all stage dependencies, DVC
+  searches backward from the target stages in the corresponding pipelines. This
+  means DVC will not pull files referenced in later stages than the `targets`.
+
+- `-R`, `--recursive` - `targets` is expected to contain one or more directories
+  for this option to have effect. Determines the files to pull by searching each
+  target directory and its subdirectories for DVC-files to inspect.
 
 - `-f`, `--force` - does not prompt when removing workspace files, which occurs
   when these file no longer match the current DVC-file references. This option
diff --git a/public/static/docs/command-reference/push.md b/public/static/docs/command-reference/push.md
index 629c9fc2dc..d337d1bfbf 100644
--- a/public/static/docs/command-reference/push.md
+++ b/public/static/docs/command-reference/push.md
@@ -81,15 +81,15 @@ to push.
   to save different experiments or project checkpoints. Note that both options
   can be combined, for example using the `-aT` flag.
 
-- `-d`, `--with-deps` - determines files to upload by tracking dependencies to
-  the target DVC-files (stages). This option only has effect when one or more
-  `targets` are specified. By traversing all stage dependencies, DVC searches
-  backward from the target stages in the corresponding pipelines. This means DVC
-  will not push files referenced in later stages than the `targets`.
-
-- `-R`, `--recursive` - `targets` is expected to contain at least one directory
-  path for this option to have effect. Determines the files to push by searching
-  each target directory and its subdirectories for DVC-files to inspect.
+- `-d`, `--with-deps` - one or more `targets` should be specified for this
+  option to have effect. Determines files to upload by tracking dependencies to
+  the target DVC-files (stages). By traversing all stage dependencies, DVC
+  searches backward from the target stages in the corresponding pipelines. This
+  means DVC will not push files referenced in later stages than the `targets`.
+
+- `-R`, `--recursive` - `targets` is expected to contain one or more directories
+  for this option to have effect. Determines the files to push by searching each
+  target directory and its subdirectories for DVC-files to inspect.
 
 - `-j JOBS`, `--jobs JOBS` - specifies number of jobs to run simultaneously
   while uploading files to the remote. The effect is to control the number of
diff --git a/public/static/docs/command-reference/repro.md b/public/static/docs/command-reference/repro.md
index 729645abbd..80e4999e4a 100644
--- a/public/static/docs/command-reference/repro.md
+++ b/public/static/docs/command-reference/repro.md
@@ -95,8 +95,8 @@ and only execute the final stage.
   reproduced as part of the pipeline in the parent directory, or as an
   independent unit.
 
-- `-R`, `--recursive` - `targets` is expected to contain at least one directory
-  path for this option to have effect. Determines the stages to reproduce by
+- `-R`, `--recursive` - `targets` is expected to contain one or more directories
+  for this option to have effect. Determines the stages to reproduce by
   searching each target directory and its subdirectories for DVC-files to
   inspect.
 
diff --git a/public/static/docs/command-reference/run.md b/public/static/docs/command-reference/run.md
index 0148e4402d..49eb29ca3e 100644
--- a/public/static/docs/command-reference/run.md
+++ b/public/static/docs/command-reference/run.md
@@ -143,8 +143,8 @@ data pipeline (e.g. random numbers, time functions, hardware dependency, etc.)
   confirmation.
 
 - `--ignore-build-cache` - This options has an effect if an equivalent stage
-  file exists (same dependencies, outputs, and `command` to execute) which has
-  been already executed and is up to date. In this case, `dvc run` won't
+  file exists (same dependencies, outputs, and `command` to execute), that has
+  been already executed, and is up to date. In this case, `dvc run` won't
   normally execute the `command` again. The exception is when the existing stage
   is considered always changed (see `--always-changed` option). This option
   gives a way to forcefully execute the `command` anyway. Useful if the
diff --git a/public/static/docs/command-reference/status.md b/public/static/docs/command-reference/status.md
index eb48971da2..559d149d21 100644
--- a/public/static/docs/command-reference/status.md
+++ b/public/static/docs/command-reference/status.md
@@ -98,12 +98,12 @@ workspace) is different from remote storage. Bringing the two into sync requires
 
 ## Options
 
-- `-d`, `--with-deps` - determines files to check by tracking dependencies to
-  the target DVC-files (stages). This option only has effect when one or more
-  `targets` are specified. By traversing all stage dependencies, DVC searches
-  backward from the target stages in the corresponding pipelines. This means DVC
-  will not show changes occurring in later stages than the `targets`. Applies
-  whether or not `--cloud` is specified.
+- `-d`, `--with-deps` - one or more `targets` should be specified for this
+  option to have effect. Determines files to check by tracking dependencies to
+  the target DVC-files (stages). By traversing all stage dependencies, DVC
+  searches backward from the target stages in the corresponding pipelines. This
+  means DVC will not show changes occurring in later stages than the `targets`.
+  Applies whether or not `--cloud` is specified.
 
 - `-c`, `--cloud` - enables comparison against a remote. (See `dvc remote`.). If
   no `--remote` option has been given, DVC will compare against the default

From 44fe4263e4f9eb0568118fd82d584e1604b5fad0 Mon Sep 17 00:00:00 2001
From: Jorge Orpinel <jorge@orpinel.com>
Date: Mon, 13 Jan 2020 20:32:46 -0600
Subject: [PATCH 10/23] server: remove man.dvc.org redirect path replace
 exceptions per
 https://github.com/iterative/dvc.org/pull/875#discussion_r366049988

---
 server.js | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/server.js b/server.js
index 8f94111f0d..9701ef1544 100644
--- a/server.js
+++ b/server.js
@@ -42,11 +42,7 @@ app.prepare().then(() => {
       res.writeHead(301, {
         'Cache-Control': 'no-cache',
         Location:
-          'https://dvc.org/doc/command-reference' +
-          // replace - for / in {cmd} except for get-url, import-url
-          (['/get-url', '/import-url'].indexOf(pathname) < 0
-            ? pathname.replace('-', '/')
-            : pathname)
+          'https://dvc.org/doc/command-reference' + pathname.replace('-', '/')
       })
       res.end()
     } else if (/^(code|data|remote)\.dvc\.org$/.test(req.headers.host)) {

From 5c078217603fd63c8ae802311a6b338379b986dd Mon Sep 17 00:00:00 2001
From: Jorge Orpinel <jorge@orpinel.com>
Date: Tue, 14 Jan 2020 13:12:15 -0600
Subject: [PATCH 11/23] user-guide: recommend Cmder for Windows terminal alt.
 per https://github.com/iterative/dvc.org/issues/698#issuecomment-558260295

---
 .../docs/user-guide/running-dvc-on-windows.md       | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/public/static/docs/user-guide/running-dvc-on-windows.md b/public/static/docs/user-guide/running-dvc-on-windows.md
index f2b79af9cb..3afbc55029 100644
--- a/public/static/docs/user-guide/running-dvc-on-windows.md
+++ b/public/static/docs/user-guide/running-dvc-on-windows.md
@@ -10,10 +10,17 @@ workarounds that can help avoid these potential problems:
 Many of the DVC commands have POSIX-style options that are given with a double
 dash `--`. This isn't supported by the simple Windows command prompt `cmd`.
 
-We recommend [Git Bash](https://gitforwindows.org/#bash) or
-[Anaconda Prompt](https://docs.anaconda.com/anaconda/user-guide/getting-started/#open-prompt-win).
-Its even possible to enjoy a full Linux terminal experience with the
+Common Windows terminal alternatives are
+[Git Bash](https://gitforwindows.org/#bash) or
+[Anaconda Prompt](https://docs.anaconda.com/anaconda/user-guide/getting-started/#open-prompt-win)
+– but they may not support all the POSIX features (e.g. `\` line continuation).
+
+**We recommend the full [Cmder](https://cmder.net/) console emulator** (which
+already includes _Git for Windows_).
+
+Its also possible to enjoy a full Linux terminal experience with the
 [WSL](https://blogs.windows.com/windowsdeveloper/2016/03/30/run-bash-on-ubuntu-on-windows/)
+– but it may not be possible to access GPUs from this subsystem.
 
 ## Disable short-file name generation
 

From 22a4044fdb3601cc598aed13bebae4927082c4c1 Mon Sep 17 00:00:00 2001
From: Jorge Orpinel <jorge@orpinel.com>
Date: Tue, 14 Jan 2020 13:16:58 -0600
Subject: [PATCH 12/23] server: no need to replace - for / in man. redirect per
 https://github.com/iterative/dvc.org/commit/44fe4263e4f9eb0568118fd82d584e1604b5fad0#r36784752

---
 server.js | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/server.js b/server.js
index 9701ef1544..3ec1bf847a 100644
--- a/server.js
+++ b/server.js
@@ -41,8 +41,7 @@ app.prepare().then(() => {
       // man.dvc.org/{cmd} -> dvc.org/doc/command-reference/{cmd},
       res.writeHead(301, {
         'Cache-Control': 'no-cache',
-        Location:
-          'https://dvc.org/doc/command-reference' + pathname.replace('-', '/')
+        Location: 'https://dvc.org/doc/command-reference' + pathname
       })
       res.end()
     } else if (/^(code|data|remote)\.dvc\.org$/.test(req.headers.host)) {

From 29f3b68651f540671910d6d564b2f8ac571aa289 Mon Sep 17 00:00:00 2001
From: Jorge Orpinel <jorge@orpinel.com>
Date: Tue, 14 Jan 2020 17:12:04 -0600
Subject: [PATCH 13/23] server: switch to HTTP 303 for most redirects per
 https://github.com/iterative/dvc.org/issues/757#issuecomment-574318350

---
 server.js | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/server.js b/server.js
index 3ec1bf847a..3d76fdf697 100644
--- a/server.js
+++ b/server.js
@@ -39,14 +39,14 @@ app.prepare().then(() => {
       res.end()
     } else if (req.headers.host === 'man.dvc.org') {
       // man.dvc.org/{cmd} -> dvc.org/doc/command-reference/{cmd},
-      res.writeHead(301, {
+      res.writeHead(303, {
         'Cache-Control': 'no-cache',
         Location: 'https://dvc.org/doc/command-reference' + pathname
       })
       res.end()
     } else if (/^(code|data|remote)\.dvc\.org$/.test(req.headers.host)) {
       // {code/data/remote}.dvc.org -> corresponding S3 bucket
-      res.writeHead(301, {
+      res.writeHead(303, {
         Location:
           'https://s3-us-east-2.amazonaws.com/dvc-public/' +
           req.headers.host.split('.')[0] +
@@ -55,7 +55,7 @@ app.prepare().then(() => {
       res.end()
     } else if (/^\/(deb|rpm)\/.*/i.test(pathname)) {
       // path /(deb|rpm)/... -> corresponding S3 bucket
-      res.writeHead(301, {
+      res.writeHead(303, {
         Location:
           'https://s3-us-east-2.amazonaws.com/dvc-s3-repo/' +
           pathname.substring(1)
@@ -63,17 +63,17 @@ app.prepare().then(() => {
       res.end()
     } else if (/^\/(help|chat)\/?$/i.test(pathname)) {
       // path /(help|chat) -> Discord chat invite
-      res.writeHead(301, { Location: 'https://discordapp.com/invite/dvwXA2N' })
+      res.writeHead(303, { Location: 'https://discordapp.com/invite/dvwXA2N' })
       res.end()
     } else if (/^\/(docs|documentation)(\/.*)?$/i.test(pathname)) {
       // path /docs... or /documentation... -> /doc...
-      res.writeHead(301, {
+      res.writeHead(303, {
         Location: req.url.replace(/\/(docs|documentation)/i, '/doc')
       })
       res.end()
     } else if (/^\/doc\/commands-reference(\/.*)?$/i.test(pathname)) {
       // path /doc/commands-reference... -> /doc/command-reference...
-      res.writeHead(301, {
+      res.writeHead(303, {
         Location: req.url.replace(
           '/doc/commands-reference',
           '/doc/command-reference'
@@ -82,13 +82,13 @@ app.prepare().then(() => {
       res.end()
     } else if (/^\/doc\/tutorial\/?$/i.test(pathname)) {
       // path /doc/tutorial -> /doc/tutorials
-      res.writeHead(301, {
+      res.writeHead(303, {
         Location: req.url.replace(/\/doc\/tutorial\/?/, '/doc/tutorials')
       })
       res.end()
     } else if (/^\/doc\/tutorial\/(.*)?/.test(pathname)) {
       // path /doc/tutorial/... -> /doc/tutorials/deep/...
-      res.writeHead(301, {
+      res.writeHead(303, {
         Location: req.url.replace('/doc/tutorial/', '/doc/tutorials/deep/')
       })
       res.end()
@@ -97,7 +97,7 @@ app.prepare().then(() => {
     ) {
       // path /doc/use-cases/data-and-model-files-versioning
       //  ->  /doc/use-cases/versioning-data-and-model-files
-      res.writeHead(301, {
+      res.writeHead(303, {
         Location: req.url.replace(
           '/doc/use-cases/data-and-model-files-versioning',
           '/doc/use-cases/versioning-data-and-model-files'

From 6f51b097615e82d40a452c7abd64394418035d7a Mon Sep 17 00:00:00 2001
From: Jorge Orpinel <jorge@orpinel.com>
Date: Tue, 14 Jan 2020 17:34:51 -0600
Subject: [PATCH 14/23] server: revert to HTTP 301 redirects for previously
 existing content to preserver "link juice" (SEO)

---
 server.js | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/server.js b/server.js
index 3d76fdf697..dd6e70937e 100644
--- a/server.js
+++ b/server.js
@@ -73,7 +73,7 @@ app.prepare().then(() => {
       res.end()
     } else if (/^\/doc\/commands-reference(\/.*)?$/i.test(pathname)) {
       // path /doc/commands-reference... -> /doc/command-reference...
-      res.writeHead(303, {
+      res.writeHead(301, {
         Location: req.url.replace(
           '/doc/commands-reference',
           '/doc/command-reference'
@@ -82,13 +82,13 @@ app.prepare().then(() => {
       res.end()
     } else if (/^\/doc\/tutorial\/?$/i.test(pathname)) {
       // path /doc/tutorial -> /doc/tutorials
-      res.writeHead(303, {
+      res.writeHead(301, {
         Location: req.url.replace(/\/doc\/tutorial\/?/, '/doc/tutorials')
       })
       res.end()
     } else if (/^\/doc\/tutorial\/(.*)?/.test(pathname)) {
       // path /doc/tutorial/... -> /doc/tutorials/deep/...
-      res.writeHead(303, {
+      res.writeHead(301, {
         Location: req.url.replace('/doc/tutorial/', '/doc/tutorials/deep/')
       })
       res.end()
@@ -97,7 +97,7 @@ app.prepare().then(() => {
     ) {
       // path /doc/use-cases/data-and-model-files-versioning
       //  ->  /doc/use-cases/versioning-data-and-model-files
-      res.writeHead(303, {
+      res.writeHead(301, {
         Location: req.url.replace(
           '/doc/use-cases/data-and-model-files-versioning',
           '/doc/use-cases/versioning-data-and-model-files'

From 44e7fcac6de7cb0e5f77d71ece067769c3fcb714 Mon Sep 17 00:00:00 2001
From: Jorge Orpinel <jorge@orpinel.com>
Date: Wed, 15 Jan 2020 18:02:26 -0600
Subject: [PATCH 15/23] cmd ref: improve import (and get) desc intro per
 https://github.com/iterative/dvc.org/pull/912#discussion_r367160227

---
 public/static/docs/command-reference/get.md    | 9 +++++----
 public/static/docs/command-reference/import.md | 8 ++++----
 2 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/public/static/docs/command-reference/get.md b/public/static/docs/command-reference/get.md
index 176e9eb31a..65f5469409 100644
--- a/public/static/docs/command-reference/get.md
+++ b/public/static/docs/command-reference/get.md
@@ -19,10 +19,11 @@ positional arguments:
 ## Description
 
 Provides an easy way to download files or directories tracked in any <abbr>DVC
-project</abbr> (e.g. datasets, ML models), or Git repository (e.g. source code,
-small images or data files). The file or directory in path is copied to the
-current working directory. (For remote URLs, it works like downloading with
-wget, but supporting DVC <abbr>data artifacts</abbr> and files tracked by Git.)
+project</abbr> (e.g. datasets, intermediate results, ML models), or Git
+repository (e.g. source code, small image/other files). `dvc get` copies the
+target file or directory (`url`/`path`) to the current working directory. (For
+remote URLs, it works like downloading with `wget`, but supporting DVC
+<abbr>data artifacts</abbr> and other files tracked in the repository.)
 
 Note that this command doesn't require an existing DVC project to run in. It's a
 single-purpose command that can be used out of the box after installing DVC.
diff --git a/public/static/docs/command-reference/import.md b/public/static/docs/command-reference/import.md
index 9b50a66a31..19c09a2806 100644
--- a/public/static/docs/command-reference/import.md
+++ b/public/static/docs/command-reference/import.md
@@ -23,10 +23,10 @@ positional arguments:
 
 Provides an easy way to reuse files or directories tracked in any <abbr>DVC
 project</abbr> (e.g. datasets, intermediate results, ML models) or Git
-repository (e.g. other files and directories), into the workspace. The
-`dvc import` command downloads such a <abbr>data artifact</abbr> in a way that
-it is tracked with DVC, so it can be updated when the data source changes. (See
-`dvc update`.)
+repository (e.g. source code, small image/other files). `dvc import` downloads
+the target file or directory (`url`/`path`) in a way so that it's tracked with
+DVC, becoming a local <abbr>data artifact</abbr>. This also permits updating the
+import later, if it has changed in its data source. (See `dvc update`.)
 
 The `url` argument specifies the address of the <abbr>DVC project</abbr> or Git
 repository containing the data source. Both HTTP and SSH protocols are supported

From 96232e0aa4e0c77aeaf8e18f2a0c35913e769a54 Mon Sep 17 00:00:00 2001
From: Jorge Orpinel <jorge@orpinel.com>
Date: Wed, 15 Jan 2020 18:12:06 -0600
Subject: [PATCH 16/23] get: improve notes about analogy vs. wget, and other
 related text addresses
 https://github.com/iterative/dvc.org/pull/912#discussion_r367160260

---
 public/static/docs/command-reference/get.md            |  3 +--
 public/static/docs/get-started/add-files.md            | 10 +++++-----
 public/static/docs/tutorials/pipelines.md              |  8 ++++----
 public/static/docs/tutorials/versioning.md             |  8 ++++----
 public/static/docs/user-guide/external-dependencies.md |  6 +++---
 5 files changed, 17 insertions(+), 18 deletions(-)

diff --git a/public/static/docs/command-reference/get.md b/public/static/docs/command-reference/get.md
index 65f5469409..c935633b4f 100644
--- a/public/static/docs/command-reference/get.md
+++ b/public/static/docs/command-reference/get.md
@@ -22,8 +22,7 @@ Provides an easy way to download files or directories tracked in any <abbr>DVC
 project</abbr> (e.g. datasets, intermediate results, ML models), or Git
 repository (e.g. source code, small image/other files). `dvc get` copies the
 target file or directory (`url`/`path`) to the current working directory. (For
-remote URLs, it works like downloading with `wget`, but supporting DVC
-<abbr>data artifacts</abbr> and other files tracked in the repository.)
+<abbr>DVC repositories</abbr>, it's analogous to `wget`.)
 
 Note that this command doesn't require an existing DVC project to run in. It's a
 single-purpose command that can be used out of the box after installing DVC.
diff --git a/public/static/docs/get-started/add-files.md b/public/static/docs/get-started/add-files.md
index ee790008f1..63f7521b9c 100644
--- a/public/static/docs/get-started/add-files.md
+++ b/public/static/docs/get-started/add-files.md
@@ -10,11 +10,11 @@ $ dvc get https://github.com/iterative/dataset-registry \
           get-started/data.xml -o data/data.xml
 ```
 
-> `dvc get` can use any <abbr>DVC project</abbr> hosted on a Git repository to
-> find the appropriate [remote storage](/doc/command-reference/remote) and
-> download <abbr>data artifacts</abbr> from it. (It works like `wget`, but for
-> DVC repositories.) In this case we use
-> [dataset-registry](https://github.com/iterative/dataset-registry) as the
+> `dvc get` can use any <abbr>DVC project</abbr> to find the appropriate
+> [remote storage](/doc/command-reference/remote) and download <abbr>data
+> artifacts</abbr> from it. (It's analogous to `wget`, but for <abbr>DVC
+> repositories</abbr>.) In this case we use
+> [dataset-registry](https://github.com/iterative/dataset-registry)) as the
 > source project. (Refer to [Data Registries](/doc/use-cases/data-registries)
 > for more info about this setup.)
 
diff --git a/public/static/docs/tutorials/pipelines.md b/public/static/docs/tutorials/pipelines.md
index 70d2fdc958..6674879b5a 100644
--- a/public/static/docs/tutorials/pipelines.md
+++ b/public/static/docs/tutorials/pipelines.md
@@ -48,10 +48,10 @@ $ git add code/
 $ git commit -m "Download and add code to new Git repo"
 ```
 
-> `dvc get` can use any <abbr>DVC project</abbr> hosted on a Git repository to
-> find the appropriate [remote storage](/doc/command-reference/remote) and
-> download <abbr>data artifacts</abbr> from it. (It works like `wget`, but for
-> DVC or Git repositories.) In this case we use
+> `dvc get` can use any <abbr>DVC project</abbr> to find the appropriate
+> [remote storage](/doc/command-reference/remote) and download <abbr>data
+> artifacts</abbr> from it. (It's analogous to `wget`, but for <abbr>DVC
+> repositories</abbr>.) In this case we use
 > [dataset-registry](https://github.com/iterative/dataset-registry)) as the
 > source project. (Refer to [Data Registries](/doc/use-cases/data-registries)
 > for more info about this setup.)
diff --git a/public/static/docs/tutorials/versioning.md b/public/static/docs/tutorials/versioning.md
index 680aeef68d..9279d31e14 100644
--- a/public/static/docs/tutorials/versioning.md
+++ b/public/static/docs/tutorials/versioning.md
@@ -83,10 +83,10 @@ $ unzip -q data.zip
 $ rm -f data.zip
 ```
 
-> `dvc get` can use any <abbr>DVC project</abbr> hosted on a Git repository to
-> find the appropriate [remote storage](/doc/command-reference/remote) and
-> download <abbr>data artifacts</abbr> from it. (It works like `wget`, but for
-> DVC repositories.) In this case we use
+> `dvc get` can use any <abbr>DVC project</abbr> to find the appropriate
+> [remote storage](/doc/command-reference/remote) and download <abbr>data
+> artifacts</abbr> from it. (It's analogous to `wget`, but for <abbr>DVC
+> repositories</abbr>.) In this case we use
 > [dataset-registry](https://github.com/iterative/dataset-registry)) as the
 > source project. (Refer to [Data Registries](/doc/use-cases/data-registries)
 > for more info about this setup.)
diff --git a/public/static/docs/user-guide/external-dependencies.md b/public/static/docs/user-guide/external-dependencies.md
index 211a727d5b..36b8a8672a 100644
--- a/public/static/docs/user-guide/external-dependencies.md
+++ b/public/static/docs/user-guide/external-dependencies.md
@@ -112,9 +112,9 @@ credentials for the different remotes.
 
 ## Example: `import-url` command
 
-In the previous examples, downloading commands were used: `aws s3 cp`, `scp`,
-`wget`, etc. `dvc import-url` simplifies the downloading for all the supported
-external path or URL types.
+In the previous examples, special downloading tools were used: `scp`,
+`aws s3 cp`, etc. `dvc import-url` simplifies the downloading for all the
+supported external path or URL types.
 
 ```dvc
 $ dvc import-url https://data.dvc.org/get-started/data.xml

From 4950d252002a3560c6a455db6402c48a5aef18c2 Mon Sep 17 00:00:00 2001
From: Jorge Orpinel <jorge@orpinel.com>
Date: Wed, 15 Jan 2020 19:02:06 -0600
Subject: [PATCH 17/23] remote: include -d option in crtain examples throughout
 website per
 https://github.com/iterative/dvc.org/pull/915#pullrequestreview-341595711

---
 public/static/docs/command-reference/config.md |  7 ++++---
 public/static/docs/command-reference/pull.md   | 13 ++++++-------
 public/static/docs/command-reference/push.md   | 11 +++++------
 .../docs/command-reference/remote/add.md       | 11 +++++++----
 .../docs/command-reference/remote/index.md     | 14 +++++++-------
 .../docs/command-reference/remote/list.md      |  7 ++++---
 .../docs/command-reference/remote/modify.md    | 18 ++++++++++--------
 .../docs/command-reference/remote/remove.md    |  5 ++---
 .../static/docs/use-cases/data-registries.md   |  2 +-
 .../docs/user-guide/managing-external-data.md  |  8 ++++----
 src/LandingHero/index.js                       |  2 +-
 11 files changed, 51 insertions(+), 47 deletions(-)

diff --git a/public/static/docs/command-reference/config.md b/public/static/docs/command-reference/config.md
index 829157fb5e..4634579068 100644
--- a/public/static/docs/command-reference/config.md
+++ b/public/static/docs/command-reference/config.md
@@ -200,18 +200,19 @@ learn more about the state file (database) that is used for optimization.
 $ dvc config core.loglevel debug
 ```
 
-## Example: Add an S3 remote
+## Example: Add an S3 remote, and set it as default
 
 > 💡 Before adding an S3 remote, be sure to
 > [Create a Bucket](https://docs.aws.amazon.com/AmazonS3/latest/gsg/CreatingABucket.html).
 
-This also sets the remote as the <abbr>project</abbr> default:
-
 ```dvc
 $ dvc remote add myremote s3://bucket/path
 $ dvc config core.remote myremote
 ```
 
+> Note that this is equivalent to using `dvc remote add` with the
+> `-d`/`--default` option.
+
 ## Example: Default remotes
 
 Use remote `myremote` by default:
diff --git a/public/static/docs/command-reference/pull.md b/public/static/docs/command-reference/pull.md
index f4fecc309f..43a27f3300 100644
--- a/public/static/docs/command-reference/pull.md
+++ b/public/static/docs/command-reference/pull.md
@@ -103,19 +103,18 @@ reflinks or hardlinks to put it in the workspace without copying. See
 ## Examples
 
 For using the `dvc pull` command, a remote storage must be defined. (See
-`dvc remote`.) For an existing <abbr>project</abbr>, remotes are usually already
-set up and you can use `dvc remote list` to check them. Just to remind how it is
-done and set a context for the example, let's define an SSH remote with the
-`dvc remote add` command:
+`dvc remote add`.) For an existing <abbr>project</abbr>, remotes are usually
+already set up and you can use `dvc remote list` to check them. To remember how
+it's done, and set a context for the example, let's define a default SSH remote:
 
 ```dvc
-$ dvc remote add r1 ssh://_username_@_host_/path/to/dvc/remote/storage
+$ dvc remote add -d r1 ssh://_username_@_host_/path/to/dvc/remote/storage
 $ dvc remote list
 r1	ssh://_username_@_host_/path/to/dvc/remote/storage
 ```
 
-> DVC supports several remote types. For details, see the
-> [`remote add`](/doc/command-reference/remote/add) documentation.
+> DVC supports several
+> [remote types](/doc/command-reference/remote/add#supported-storage-types).
 
 Having some images and other files in remote storage, we can pull all changed
 files from the current Git branch:
diff --git a/public/static/docs/command-reference/push.md b/public/static/docs/command-reference/push.md
index d337d1bfbf..3b73ba2bcd 100644
--- a/public/static/docs/command-reference/push.md
+++ b/public/static/docs/command-reference/push.md
@@ -107,10 +107,9 @@ to push.
 ## Examples
 
 For using the `dvc push` command, a remote storage must be defined. (See
-`dvc remote`.) For an existing <abbr>project</abbr>, remotes are usually already
-set up and you can use `dvc remote list` to check them. Just to remind how it is
-done and set a context for the example, let's define an SSH remote with the
-`dvc remote add` command:
+`dvc remote add`.) For an existing <abbr>project</abbr>, remotes are usually
+already set up and you can use `dvc remote list` to check them. To remember how
+it's done, and set a context for the example, let's define a default SSH remote:
 
 ```dvc
 $ dvc remote add r1 ssh://_username_@_host_/path/to/dvc/cache/directory
@@ -118,8 +117,8 @@ $ dvc remote list
 r1	ssh://_username_@_host_/path/to/dvc/cache/directory
 ```
 
-> DVC supports several remote types. For details, see the
-> [`remote add`](/doc/command-reference/remote/add) documentation.
+> DVC supports several
+> [remote types](/doc/command-reference/remote/add#supported-storage-types).
 
 Push all data file caches from the current Git branch to the default remote:
 
diff --git a/public/static/docs/command-reference/remote/add.md b/public/static/docs/command-reference/remote/add.md
index 1d758dd87e..c6dbd6166d 100644
--- a/public/static/docs/command-reference/remote/add.md
+++ b/public/static/docs/command-reference/remote/add.md
@@ -132,10 +132,10 @@ To communicate with a remote object storage that supports an S3 compatible API
 [IBM Cloud Object Storage](https://www.ibm.com/cloud/object-storage) etc.) you
 must explicitly set the `endpointurl` in the configuration:
 
-For example:
+For example, using `dvc remote modify`:
 
 ```dvc
-$ dvc remote add -d myremote s3://mybucket/path/to/dir
+$ dvc remote add myremote s3://mybucket/path/to/dir
 $ dvc remote modify myremote endpointurl https://object-storage.example.com
 ```
 
@@ -390,10 +390,13 @@ $ cat .dvc/config
 
 </details>
 
-## Example: Custom configuration of an S3 remote
+## Example: Customize an S3 remote
 
 Add an Amazon S3 remote as the _default_ (via `-d` option), and modify its
-region:
+region.
+
+> 💡 Before adding an S3 remote, be sure to
+> [Create a Bucket](https://docs.aws.amazon.com/AmazonS3/latest/gsg/CreatingABucket.html).
 
 ```dvc
 $ dvc remote add -d myremote s3://mybucket/myproject
diff --git a/public/static/docs/command-reference/remote/index.md b/public/static/docs/command-reference/remote/index.md
index a0ded7d708..cbe8a8947c 100644
--- a/public/static/docs/command-reference/remote/index.md
+++ b/public/static/docs/command-reference/remote/index.md
@@ -95,14 +95,14 @@ url = /path/to/remote
 remote = myremote
 ```
 
-## Example: Add an Amazon S3 remote and modify its region
+## Example: Customize an additional S3 remote
 
 > 💡 Before adding an S3 remote, be sure to
 > [Create a Bucket](https://docs.aws.amazon.com/AmazonS3/latest/gsg/CreatingABucket.html).
 
 ```dvc
-$ dvc remote add mynewremote s3://mybucket/myproject
-$ dvc remote modify mynewremote region us-east-2
+$ dvc remote add newremote s3://mybucket/myproject
+$ dvc remote modify newremote endpointurl https://object-storage.example.com
 ```
 
 The project's config file should now look something like this:
@@ -112,9 +112,9 @@ The project's config file should now look something like this:
 url = /path/to/remote
 [core]
 remote = myremote
-['remote "mynewremote"']
+['remote "newremote"']
 url = s3://mybucket/myproject
-region = us-east-2
+endpointurl = https://object-storage.example.com
 ```
 
 ## Example: List all remotes in the project
@@ -122,11 +122,11 @@ region = us-east-2
 ```dvc
 $ dvc remote list
 myremote	/path/to/remote
-mynewremote	s3://mybucket/myproject
+newremote	s3://mybucket/myproject
 ```
 
 ## Example: Remove a remote
 
 ```dvc
-$ dvc remote remove mynewremote
+$ dvc remote remove newremote
 ```
diff --git a/public/static/docs/command-reference/remote/list.md b/public/static/docs/command-reference/remote/list.md
index 67e9a6fd46..fa01afee72 100644
--- a/public/static/docs/command-reference/remote/list.md
+++ b/public/static/docs/command-reference/remote/list.md
@@ -38,7 +38,7 @@ including names and URLs.
 
 ## Examples
 
-Let's for simplicity add a default local remote:
+Let's for simplicity add a _default_ local remote:
 
 <details>
 
@@ -60,6 +60,7 @@ And now the list of remotes should look like:
 
 ```dvc
 $ dvc remote list
-
-myremote        /path/to/remote
+myremote	/path/to/remote
 ```
+
+The list will also include any previously added remotes.
diff --git a/public/static/docs/command-reference/remote/modify.md b/public/static/docs/command-reference/remote/modify.md
index cb235aba52..b2cac198bd 100644
--- a/public/static/docs/command-reference/remote/modify.md
+++ b/public/static/docs/command-reference/remote/modify.md
@@ -185,7 +185,7 @@ must explicitly set the `endpointurl` in the configuration:
 For example:
 
 ```dvc
-$ dvc remote add -d myremote s3://path/to/dir
+$ dvc remote add myremote s3://path/to/dir
 $ dvc remote modify myremote endpointurl https://object-storage.example.com
 ```
 
@@ -382,26 +382,28 @@ For more information on configuring Azure Storage connection strings, visit
 
 ## Example: Customize an S3 remote
 
-Let's first set up a _default_ S3 remote:
+Let's first set up a _default_ S3 remote.
 
-```dvc
-$ dvc remote add -d myremote s3://mybucket/storage
+> 💡 Before adding an S3 remote, be sure to
+> [Create a Bucket](https://docs.aws.amazon.com/AmazonS3/latest/gsg/CreatingABucket.html).
 
+```dvc
+$ dvc remote add -d myremote s3://mybucket/myproject
 Setting 'myremote' as a default remote.
 ```
 
-Modify its endpoint URL:
+Modify its access profile:
 
 ```dvc
-$ dvc remote modify myremote endpointurl https://object-storage.example.com
+$ dvc remote modify myremote profile myusername
 ```
 
-Now the config file should look like (run `cat .dvc/config`):
+Now the project config file should look like this:
 
 ```ini
 ['remote "myremote"']
 url = s3://mybucket/storage
-endpointurl = https://object-storage.example.com
+profile = myusername
 [core]
 remote = myremote
 ```
diff --git a/public/static/docs/command-reference/remote/remove.md b/public/static/docs/command-reference/remote/remove.md
index 0028eedb2e..d69028876b 100644
--- a/public/static/docs/command-reference/remote/remove.md
+++ b/public/static/docs/command-reference/remote/remove.md
@@ -47,14 +47,13 @@ edit config files manually.
 
 ## Examples
 
-Add Amazon S3 remote and modify its region:
+Add Amazon S3 remote:
 
 ```dvc
 $ dvc remote add myremote s3://mybucket/myproject
-$ dvc remote modify myremote region us-east-2
 ```
 
-Remove remote:
+Remove it:
 
 ```dvc
 $ dvc remote remove myremote
diff --git a/public/static/docs/use-cases/data-registries.md b/public/static/docs/use-cases/data-registries.md
index a52340f3a8..a2cb55f8a5 100644
--- a/public/static/docs/use-cases/data-registries.md
+++ b/public/static/docs/use-cases/data-registries.md
@@ -82,7 +82,7 @@ The actual data is stored in the project's <abbr>cache</abbr> and should be
 be accessed from other locations or by other people:
 
 ```
-$ dvc remote add myremote s3://bucket/path
+$ dvc remote add -d myremote s3://bucket/path
 $ dvc push
 ```
 
diff --git a/public/static/docs/user-guide/managing-external-data.md b/public/static/docs/user-guide/managing-external-data.md
index b2c7c91fa9..27a330dded 100644
--- a/public/static/docs/user-guide/managing-external-data.md
+++ b/public/static/docs/user-guide/managing-external-data.md
@@ -68,7 +68,7 @@ $ dvc run -d data.txt \
 # Add SSH remote to be used as cache location for SSH files
 $ dvc remote add sshcache ssh://user@example.com:/cache
 
-# Tell dvc to use the 'sshcache' remote as SSH cache location
+# Tell DVC to use the 'sshcache' remote as SSH cache location
 $ dvc config cache.ssh sshcache
 
 # Add data on SSH directly
@@ -86,7 +86,7 @@ $ dvc run -d data.txt \
 # Add S3 remote to be used as cache location for S3 files
 $ dvc remote add s3cache s3://mybucket/cache
 
-# Tell dvc to use the 's3cache' remote as S3 cache location
+# Tell DVC to use the 's3cache' remote as S3 cache location
 $ dvc config cache.s3 s3cache
 
 # Add data on S3 directly
@@ -104,7 +104,7 @@ $ dvc run -d data.txt \
 # Add GS remote to be used as cache location for GS files
 $ dvc remote add gscache gs://mybucket/cache
 
-# Tell dvc to use the 'gscache' remote as GS cache location
+# Tell DVC to use the 'gscache' remote as GS cache location
 $ dvc config cache.gs gscache
 
 # Add data on GS directly
@@ -122,7 +122,7 @@ $ dvc run -d data.txt \
 # Add HDFS remote to be used as cache location for HDFS files
 $ dvc remote add hdfscache hdfs://user@example.com/cache
 
-# Tell dvc to use the 'hdfscache' remote as HDFS cache location
+# Tell DVC to use the 'hdfscache' remote as HDFS cache location
 $ dvc config cache.hdfs hdfscache
 
 # Add data on HDFS directly
diff --git a/src/LandingHero/index.js b/src/LandingHero/index.js
index e13507ea8e..fa2af551ed 100644
--- a/src/LandingHero/index.js
+++ b/src/LandingHero/index.js
@@ -91,7 +91,7 @@ export default class LandingHero extends Component {
               <Line>$ dvc run -d images -o model.p cnn.py</Line>
             </Command>
             <Command active={activeCommand === 2}>
-              <Line>$ dvc remote add myrepo s3://mybucket</Line>
+              <Line>$ dvc remote add -d myrepo s3://mybucket</Line>
             </Command>
             <Command active={activeCommand === 3}>
               <Line>$ dvc push</Line>

From 6ac834e0375e11c41d5e9aaa38a0c9b19f05f545 Mon Sep 17 00:00:00 2001
From: Jorge Orpinel <jorge@orpinel.com>
Date: Thu, 16 Jan 2020 11:18:43 -0600
Subject: [PATCH 18/23] es6: remove comments between import groups throughout
 per https://github.com/iterative/dvc.org/issues/789#issuecomment-573267931

---
 pages/doc.js                                 |  6 +++---
 server.js                                    |  1 -
 src/Documentation/Markdown/Markdown.js       | 10 +++++-----
 src/Documentation/RightPanel/RightPanel.js   |  2 +-
 src/Documentation/SidebarMenu/SidebarMenu.js | 10 +++++-----
 src/Layout/index.js                          |  4 ++--
 src/PromoSection/index.js                    |  2 +-
 src/TopMenu/index.js                         |  8 ++++----
 8 files changed, 21 insertions(+), 22 deletions(-)

diff --git a/pages/doc.js b/pages/doc.js
index 4030113bfc..556556449c 100644
--- a/pages/doc.js
+++ b/pages/doc.js
@@ -7,7 +7,7 @@ import Error from 'next/error'
 import Router from 'next/router'
 import fetch from 'isomorphic-fetch'
 import kebabCase from 'lodash.kebabcase'
-// components
+
 import Page from '../src/Page'
 import { HeadInjector } from '../src/Documentation/HeadInjector'
 import Hamburger from '../src/Hamburger'
@@ -15,9 +15,9 @@ import SearchForm from '../src/SearchForm'
 import SidebarMenu from '../src/Documentation/SidebarMenu/SidebarMenu'
 import Markdown from '../src/Documentation/Markdown/Markdown'
 import RightPanel from '../src/Documentation/RightPanel/RightPanel'
-// sidebar data and helpers
+
 import { getItemByPath, structure } from '../src/utils/sidebar'
-// styles
+
 import { media } from '../src/styles'
 
 const ROOT_ELEMENT = 'bodybag'
diff --git a/server.js b/server.js
index 1c8d048cd1..ddc9d089a9 100644
--- a/server.js
+++ b/server.js
@@ -1,5 +1,4 @@
 /* eslint-env node */
-
 /*
  * Custom server (with custom routes) See
  * https://nextjs.org/docs/advanced-features/custom-server
diff --git a/src/Documentation/Markdown/Markdown.js b/src/Documentation/Markdown/Markdown.js
index 60f1f95f35..9fb18ea255 100644
--- a/src/Documentation/Markdown/Markdown.js
+++ b/src/Documentation/Markdown/Markdown.js
@@ -2,13 +2,13 @@ import React from 'react'
 import PropTypes from 'prop-types'
 import NextLink from 'next/link'
 import Router from 'next/router'
-// components
+
 import ReactMarkdown from 'react-markdown'
 import { LightButton } from '../LightButton'
 import Tutorials from '../Tutorials'
 import Tooltip from '../../Tooltip'
 import Collapsible from 'react-collapsible'
-// syntax highlighter
+
 import { Light as SyntaxHighlighter } from 'react-syntax-highlighter'
 import { docco } from 'react-syntax-highlighter/dist/cjs/styles/hljs'
 import python from 'react-syntax-highlighter/dist/cjs/languages/hljs/python'
@@ -20,11 +20,11 @@ import vim from 'react-syntax-highlighter/dist/cjs/languages/hljs/vim'
 import usage from './lang/usage'
 import dvc from './lang/dvc'
 import linker from './utils/remark-linker'
-// consts
+
 import { PAGE_DOC } from '../../consts'
-// utils
+
 import kebabCase from 'lodash.kebabcase'
-// styles
+
 import styled from 'styled-components'
 import { media } from '../../../src/styles'
 
diff --git a/src/Documentation/RightPanel/RightPanel.js b/src/Documentation/RightPanel/RightPanel.js
index 085d54a74c..187574aa3e 100644
--- a/src/Documentation/RightPanel/RightPanel.js
+++ b/src/Documentation/RightPanel/RightPanel.js
@@ -3,7 +3,7 @@ import PropTypes from 'prop-types'
 import styled from 'styled-components'
 import { LightButton } from '../LightButton'
 import Tutorials from '../Tutorials'
-// utils
+
 import throttle from 'lodash.throttle'
 
 const ROOT_ELEMENT = 'bodybag'
diff --git a/src/Documentation/SidebarMenu/SidebarMenu.js b/src/Documentation/SidebarMenu/SidebarMenu.js
index e5f1ab0811..48f90ad036 100644
--- a/src/Documentation/SidebarMenu/SidebarMenu.js
+++ b/src/Documentation/SidebarMenu/SidebarMenu.js
@@ -3,16 +3,16 @@ import PerfectScrollbar from 'perfect-scrollbar'
 import scrollIntoView from 'dom-scroll-into-view'
 import PropTypes from 'prop-types'
 import NextLink from 'next/link'
-// consts
+
 import { PAGE_DOC } from '../../consts'
-// components
+
 import DownloadButton from '../../DownloadButton'
-// utils
+
 import includes from 'lodash.includes'
-// styles
+
 import styled from 'styled-components'
 import { OnlyDesktop, media } from '../../styles'
-// sidebar helpers
+
 import { getParentsListFromPath } from '../../utils/sidebar'
 
 /** Height of each menu child items (to calc Element weight for animations) */
diff --git a/src/Layout/index.js b/src/Layout/index.js
index 016130e2f5..c7e5563a12 100644
--- a/src/Layout/index.js
+++ b/src/Layout/index.js
@@ -2,11 +2,11 @@ import React, { useEffect } from 'react'
 import PropTypes from 'prop-types'
 import styled from 'styled-components'
 import { useRouter } from 'next/router'
-// components
+
 import TopMenu from '../TopMenu'
 import Footer from '../Footer'
 import HamburgerMenu from '../HamburgerMenu'
-// utils
+
 import { initGA, logPageView } from '../utils/ga'
 
 export default function Layout({ children, enableSmoothScroll }) {
diff --git a/src/PromoSection/index.js b/src/PromoSection/index.js
index c396551be4..c608dd1501 100644
--- a/src/PromoSection/index.js
+++ b/src/PromoSection/index.js
@@ -3,7 +3,7 @@ import styled from 'styled-components'
 import Router from 'next/router'
 import { media } from '../styles'
 import { logEvent } from '../utils/ga'
-// consts
+
 import { PAGE_DOC } from '../consts'
 
 function goToDocGetStarted() {
diff --git a/src/TopMenu/index.js b/src/TopMenu/index.js
index 9633fdf86a..c9f6cb7f3c 100644
--- a/src/TopMenu/index.js
+++ b/src/TopMenu/index.js
@@ -1,14 +1,14 @@
 import React, { Component } from 'react'
 import PropTypes from 'prop-types'
 import NextLink from 'next/link'
-// components
+
 import Nav from '../Nav'
-// utils
+
 import throttle from 'lodash.throttle'
-// styles
+
 import styled from 'styled-components'
 import { media } from '../styles'
-// constants
+
 import { HEADER } from '../consts'
 
 const MIN_HEIGHT = 78

From 7ea2edbf887abfe8204a85483b164ec6e37645c7 Mon Sep 17 00:00:00 2001
From: Jorge Orpinel <jorge@orpinel.com>
Date: Thu, 16 Jan 2020 11:46:35 -0600
Subject: [PATCH 19/23] es6: manual import sort of 3 basic files per
 https://github.com/iterative/dvc.org/issues/789#issuecomment-574973027

---
 pages/doc.js         | 15 +++++++--------
 server.js            |  2 +-
 src/utils/sidebar.js |  1 +
 3 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/pages/doc.js b/pages/doc.js
index 556556449c..f23aebada3 100644
--- a/pages/doc.js
+++ b/pages/doc.js
@@ -1,12 +1,14 @@
 /* global docsearch:readonly */
 
-import React, { useCallback, useEffect, useState } from 'react'
-import PropTypes from 'prop-types'
-import styled from 'styled-components'
-import Error from 'next/error'
+import React, { useState, useCallback, useEffect } from 'react'
+import kebabCase from 'lodash.kebabcase'
+import Error from 'next/error' // comp
 import Router from 'next/router'
 import fetch from 'isomorphic-fetch'
-import kebabCase from 'lodash.kebabcase'
+import PropTypes from 'prop-types'
+import styled from 'styled-components'
+
+import { structure, getItemByPath } from '../src/utils/sidebar'
 
 import Page from '../src/Page'
 import { HeadInjector } from '../src/Documentation/HeadInjector'
@@ -15,9 +17,6 @@ import SearchForm from '../src/SearchForm'
 import SidebarMenu from '../src/Documentation/SidebarMenu/SidebarMenu'
 import Markdown from '../src/Documentation/Markdown/Markdown'
 import RightPanel from '../src/Documentation/RightPanel/RightPanel'
-
-import { getItemByPath, structure } from '../src/utils/sidebar'
-
 import { media } from '../src/styles'
 
 const ROOT_ELEMENT = 'bodybag'
diff --git a/server.js b/server.js
index ddc9d089a9..7c24b8c819 100644
--- a/server.js
+++ b/server.js
@@ -8,9 +8,9 @@
  * are running.
  */
 
+const next = require('next')
 const { createServer } = require('http')
 const { parse } = require('url')
-const next = require('next')
 
 const { getItemByPath } = require('./src/utils/sidebar')
 
diff --git a/src/utils/sidebar.js b/src/utils/sidebar.js
index 0135d87975..296cb80eb3 100644
--- a/src/utils/sidebar.js
+++ b/src/utils/sidebar.js
@@ -19,6 +19,7 @@
 */
 
 const startCase = require('lodash.startcase')
+
 const sidebar = require('../../public/static/docs/sidebar.json')
 
 const PATH_ROOT = '/doc/'

From 3b21ffdc27f6cec5f710a0af2782507acf73a9ee Mon Sep 17 00:00:00 2001
From: Jorge Orpinel <jorge@orpinel.com>
Date: Thu, 16 Jan 2020 13:47:27 -0600
Subject: [PATCH 20/23] docs: copy edits per
 https://github.com/iterative/dvc.org/pull/915#pullrequestreview-343668022 and
 https://github.com/iterative/dvc.org/pull/915#pullrequestreview-343668503

---
 public/static/docs/command-reference/config.md          | 4 ++--
 public/static/docs/user-guide/running-dvc-on-windows.md | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/public/static/docs/command-reference/config.md b/public/static/docs/command-reference/config.md
index 4634579068..29f3d3b47d 100644
--- a/public/static/docs/command-reference/config.md
+++ b/public/static/docs/command-reference/config.md
@@ -110,8 +110,8 @@ for more details.) This section contains the following options:
   > directory into paths relative to the config file location.
 
 - `cache.protected` - make files under DVC control read-only. Possible values
-  are `true` or `false` (default). Run `dvc checkout` after setting changing the
-  value for this option for the change to go into effect.
+  are `true` or `false` (default). Run `dvc checkout` after changing the value
+  of this option for the change to go into effect.
 
   Due to the way DVC handles linking between the data files in the cache and
   their counterparts in the <abbr>workspace</abbr>, it's easy to accidentally
diff --git a/public/static/docs/user-guide/running-dvc-on-windows.md b/public/static/docs/user-guide/running-dvc-on-windows.md
index 3afbc55029..c88f7118f9 100644
--- a/public/static/docs/user-guide/running-dvc-on-windows.md
+++ b/public/static/docs/user-guide/running-dvc-on-windows.md
@@ -15,7 +15,7 @@ Common Windows terminal alternatives are
 [Anaconda Prompt](https://docs.anaconda.com/anaconda/user-guide/getting-started/#open-prompt-win)
 – but they may not support all the POSIX features (e.g. `\` line continuation).
 
-**We recommend the full [Cmder](https://cmder.net/) console emulator** (which
+💡 We recommend the full [Cmder](https://cmder.net/) console emulator (which
 already includes _Git for Windows_).
 
 Its also possible to enjoy a full Linux terminal experience with the

From c64d5906770fa80a04380bdc7228ab992059add4 Mon Sep 17 00:00:00 2001
From: Jorge Orpinel <jorge@orpinel.com>
Date: Sat, 18 Jan 2020 13:33:11 -0600
Subject: [PATCH 21/23] Revert "es6: manual import sort of 3 basic files" and
 Revert "es6: remove comments between import groups throughout"

with git revert 6ac834e^..7ea2edb (and then squash)
---
 pages/doc.js                                 | 17 +++++++++--------
 server.js                                    |  3 ++-
 src/Documentation/Markdown/Markdown.js       | 10 +++++-----
 src/Documentation/RightPanel/RightPanel.js   |  2 +-
 src/Documentation/SidebarMenu/SidebarMenu.js | 10 +++++-----
 src/Layout/index.js                          |  4 ++--
 src/PromoSection/index.js                    |  2 +-
 src/TopMenu/index.js                         |  8 ++++----
 src/utils/sidebar.js                         |  1 -
 9 files changed, 29 insertions(+), 28 deletions(-)

diff --git a/pages/doc.js b/pages/doc.js
index f23aebada3..4030113bfc 100644
--- a/pages/doc.js
+++ b/pages/doc.js
@@ -1,15 +1,13 @@
 /* global docsearch:readonly */
 
-import React, { useState, useCallback, useEffect } from 'react'
-import kebabCase from 'lodash.kebabcase'
-import Error from 'next/error' // comp
-import Router from 'next/router'
-import fetch from 'isomorphic-fetch'
+import React, { useCallback, useEffect, useState } from 'react'
 import PropTypes from 'prop-types'
 import styled from 'styled-components'
-
-import { structure, getItemByPath } from '../src/utils/sidebar'
-
+import Error from 'next/error'
+import Router from 'next/router'
+import fetch from 'isomorphic-fetch'
+import kebabCase from 'lodash.kebabcase'
+// components
 import Page from '../src/Page'
 import { HeadInjector } from '../src/Documentation/HeadInjector'
 import Hamburger from '../src/Hamburger'
@@ -17,6 +15,9 @@ import SearchForm from '../src/SearchForm'
 import SidebarMenu from '../src/Documentation/SidebarMenu/SidebarMenu'
 import Markdown from '../src/Documentation/Markdown/Markdown'
 import RightPanel from '../src/Documentation/RightPanel/RightPanel'
+// sidebar data and helpers
+import { getItemByPath, structure } from '../src/utils/sidebar'
+// styles
 import { media } from '../src/styles'
 
 const ROOT_ELEMENT = 'bodybag'
diff --git a/server.js b/server.js
index 7c24b8c819..1c8d048cd1 100644
--- a/server.js
+++ b/server.js
@@ -1,4 +1,5 @@
 /* eslint-env node */
+
 /*
  * Custom server (with custom routes) See
  * https://nextjs.org/docs/advanced-features/custom-server
@@ -8,9 +9,9 @@
  * are running.
  */
 
-const next = require('next')
 const { createServer } = require('http')
 const { parse } = require('url')
+const next = require('next')
 
 const { getItemByPath } = require('./src/utils/sidebar')
 
diff --git a/src/Documentation/Markdown/Markdown.js b/src/Documentation/Markdown/Markdown.js
index 9fb18ea255..60f1f95f35 100644
--- a/src/Documentation/Markdown/Markdown.js
+++ b/src/Documentation/Markdown/Markdown.js
@@ -2,13 +2,13 @@ import React from 'react'
 import PropTypes from 'prop-types'
 import NextLink from 'next/link'
 import Router from 'next/router'
-
+// components
 import ReactMarkdown from 'react-markdown'
 import { LightButton } from '../LightButton'
 import Tutorials from '../Tutorials'
 import Tooltip from '../../Tooltip'
 import Collapsible from 'react-collapsible'
-
+// syntax highlighter
 import { Light as SyntaxHighlighter } from 'react-syntax-highlighter'
 import { docco } from 'react-syntax-highlighter/dist/cjs/styles/hljs'
 import python from 'react-syntax-highlighter/dist/cjs/languages/hljs/python'
@@ -20,11 +20,11 @@ import vim from 'react-syntax-highlighter/dist/cjs/languages/hljs/vim'
 import usage from './lang/usage'
 import dvc from './lang/dvc'
 import linker from './utils/remark-linker'
-
+// consts
 import { PAGE_DOC } from '../../consts'
-
+// utils
 import kebabCase from 'lodash.kebabcase'
-
+// styles
 import styled from 'styled-components'
 import { media } from '../../../src/styles'
 
diff --git a/src/Documentation/RightPanel/RightPanel.js b/src/Documentation/RightPanel/RightPanel.js
index 187574aa3e..085d54a74c 100644
--- a/src/Documentation/RightPanel/RightPanel.js
+++ b/src/Documentation/RightPanel/RightPanel.js
@@ -3,7 +3,7 @@ import PropTypes from 'prop-types'
 import styled from 'styled-components'
 import { LightButton } from '../LightButton'
 import Tutorials from '../Tutorials'
-
+// utils
 import throttle from 'lodash.throttle'
 
 const ROOT_ELEMENT = 'bodybag'
diff --git a/src/Documentation/SidebarMenu/SidebarMenu.js b/src/Documentation/SidebarMenu/SidebarMenu.js
index 48f90ad036..e5f1ab0811 100644
--- a/src/Documentation/SidebarMenu/SidebarMenu.js
+++ b/src/Documentation/SidebarMenu/SidebarMenu.js
@@ -3,16 +3,16 @@ import PerfectScrollbar from 'perfect-scrollbar'
 import scrollIntoView from 'dom-scroll-into-view'
 import PropTypes from 'prop-types'
 import NextLink from 'next/link'
-
+// consts
 import { PAGE_DOC } from '../../consts'
-
+// components
 import DownloadButton from '../../DownloadButton'
-
+// utils
 import includes from 'lodash.includes'
-
+// styles
 import styled from 'styled-components'
 import { OnlyDesktop, media } from '../../styles'
-
+// sidebar helpers
 import { getParentsListFromPath } from '../../utils/sidebar'
 
 /** Height of each menu child items (to calc Element weight for animations) */
diff --git a/src/Layout/index.js b/src/Layout/index.js
index c7e5563a12..016130e2f5 100644
--- a/src/Layout/index.js
+++ b/src/Layout/index.js
@@ -2,11 +2,11 @@ import React, { useEffect } from 'react'
 import PropTypes from 'prop-types'
 import styled from 'styled-components'
 import { useRouter } from 'next/router'
-
+// components
 import TopMenu from '../TopMenu'
 import Footer from '../Footer'
 import HamburgerMenu from '../HamburgerMenu'
-
+// utils
 import { initGA, logPageView } from '../utils/ga'
 
 export default function Layout({ children, enableSmoothScroll }) {
diff --git a/src/PromoSection/index.js b/src/PromoSection/index.js
index c608dd1501..c396551be4 100644
--- a/src/PromoSection/index.js
+++ b/src/PromoSection/index.js
@@ -3,7 +3,7 @@ import styled from 'styled-components'
 import Router from 'next/router'
 import { media } from '../styles'
 import { logEvent } from '../utils/ga'
-
+// consts
 import { PAGE_DOC } from '../consts'
 
 function goToDocGetStarted() {
diff --git a/src/TopMenu/index.js b/src/TopMenu/index.js
index c9f6cb7f3c..9633fdf86a 100644
--- a/src/TopMenu/index.js
+++ b/src/TopMenu/index.js
@@ -1,14 +1,14 @@
 import React, { Component } from 'react'
 import PropTypes from 'prop-types'
 import NextLink from 'next/link'
-
+// components
 import Nav from '../Nav'
-
+// utils
 import throttle from 'lodash.throttle'
-
+// styles
 import styled from 'styled-components'
 import { media } from '../styles'
-
+// constants
 import { HEADER } from '../consts'
 
 const MIN_HEIGHT = 78
diff --git a/src/utils/sidebar.js b/src/utils/sidebar.js
index 296cb80eb3..0135d87975 100644
--- a/src/utils/sidebar.js
+++ b/src/utils/sidebar.js
@@ -19,7 +19,6 @@
 */
 
 const startCase = require('lodash.startcase')
-
 const sidebar = require('../../public/static/docs/sidebar.json')
 
 const PATH_ROOT = '/doc/'

From cc376793048d99b8235b9fc38b18c6c9248b19a8 Mon Sep 17 00:00:00 2001
From: Jorge Orpinel <jorge@orpinel.com>
Date: Sat, 18 Jan 2020 13:44:57 -0600
Subject: [PATCH 22/23] server: make \/(docs|documentation) redirect 301 per
 https://github.com/iterative/dvc.org/pull/915#pullrequestreview-344226517

---
 server.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/server.js b/server.js
index 1c8d048cd1..d0554acbb3 100644
--- a/server.js
+++ b/server.js
@@ -77,7 +77,7 @@ app.prepare().then(() => {
       res.end()
     } else if (/^\/(docs|documentation)(\/.*)?$/i.test(pathname)) {
       // path /docs... or /documentation... -> /doc...
-      res.writeHead(303, {
+      res.writeHead(301, {
         Location: req.url.replace(/\/(docs|documentation)/i, '/doc')
       })
       res.end()

From 86972d4cb76e9dc94f328a7c1879f32e013ffa75 Mon Sep 17 00:00:00 2001
From: Jorge Orpinel <jorge@orpinel.com>
Date: Sat, 18 Jan 2020 13:50:01 -0600
Subject: [PATCH 23/23] cmd ref: fix example title in get per
 https://github.com/iterative/dvc.org/pull/925#pullrequestreview-344906205

---
 public/static/docs/command-reference/get.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/public/static/docs/command-reference/get.md b/public/static/docs/command-reference/get.md
index c935633b4f..39775a4488 100644
--- a/public/static/docs/command-reference/get.md
+++ b/public/static/docs/command-reference/get.md
@@ -108,9 +108,9 @@ The same example applies to raw or intermediate <abbr>data artifacts</abbr> as
 well, of course, for cases where we want to download those files or directories
 and perform some analysis on them.
 
-## Examples: Get a Git-tracked model file
+## Examples: Get a misc. Git-tracked file
 
-We can also use `dvc get` to retrieve any file or directory that exists in a git
+We can also use `dvc get` to retrieve any file or directory that exists in a Git
 repository.
 
 ```dvc