treeverse · shcheklein · Oct 28, 2019 · Oct 23, 2019 · Oct 23, 2019 · Oct 25, 2019
diff --git a/src/Documentation/glossary.js b/src/Documentation/glossary.js
@@ -43,7 +43,7 @@ For more details, please refer to this
       desc: `
 Any data file or directory, as well as intermediate or final result (such as
 extracted features or a ML model file) that is under DVC control. Refer to
-[Data and Model Files Versioning](/doc/use-cases/data-and-model-files-versioning)
+[Versioning Data and Model Files](/doc/use-cases/versioning-data-and-model-files)
 for more details.
       `
     },

diff --git a/src/Documentation/sidebar.json b/src/Documentation/sidebar.json
@@ -89,12 +89,12 @@
     "source": "use-cases/index.md",
     "children": [
       {
-        "label": "Data & Model Files Versioning",
-        "slug": "data-and-model-files-versioning"
+        "label": "Versioning Data & Model Files",
+        "slug": "versioning-data-and-model-files"
       },
       {
-        "label": "Share Data & Model Files",
-        "slug": "share-data-and-model-files"
+        "label": "Sharing Data & Model Files",
+        "slug": "sharing-data-and-model-files"
       },
       "shared-development-server"
     ]
@@ -112,7 +112,7 @@
         "slug": "dvc-file-format"
       },
       "dvcignore",
-      "update-tracked-files",
+      "updating-tracked-files",
       "large-dataset-optimization",
       "external-dependencies",
       {

diff --git a/static/docs/changelog/0.35.md b/static/docs/changelog/0.35.md
@@ -52,10 +52,10 @@ improvements) we have done in the last few months:
   wherever you want with the `-f` option supported by all relevant commands -
   `dvc add`, `dvc run`, and `dvc import`.
 
-- 🙂A lot of **UI improvements** . Starting from the finally fixed nasty issue
-  with Windows terminal printing a lot of garbage symbols, to using progress
-  bars for checkouts, better metrics output, and lots of smaller things:
-  ![|528x200](/static/img/0.35-metrics.gif)
+- 🙂 A lot of **UI improvements** . Starting from the finally fixed nasty issue
+  with Windows command prompt printing a lot of garbage symbols, to using
+  progress bars for checkouts, better metrics output, and lots of smaller
+  things: ![|528x200](/static/img/0.35-metrics.gif)
 
 - **⚡️Performance optimizations.** The most notable one is the migration from
   using the plain JSON file to the embedded SQLLite engine to cache file and
@@ -65,8 +65,8 @@ improvements) we have done in the last few months:
 
 There are new [integrations and plugins](/doc/install/plugins) available:
 
-- Finally there is an official
-  [Bash and Zsh completion](/doc/install/completion) for DVC!
+- Finally there is official [Bash and Zsh completion](/doc/install/completion)
+  for DVC!
 - David Příhoda contributed and is developing the
   [JetBrains IDEs plugin](https://plugins.jetbrains.com/plugin/11368-data-version-control-dvc-support)
   (PyCharm, IntelliJ, etc).

diff --git a/static/docs/command-reference/commit.md b/static/docs/command-reference/commit.md
@@ -109,8 +109,8 @@ $ cd example-get-started
 ```
 
 Now let's install the requirements. But before we do that, we **strongly**
-recommend creating a virtual environment with a tool such as
-[virtualenv](https://virtualenv.pypa.io/en/stable/):
+recommend creating a
+[virtual environment](https://packaging.python.org/tutorials/installing-packages/#creating-virtual-environments):
 
 ```dvc
 $ virtualenv -p python3 .env

diff --git a/static/docs/command-reference/destroy.md b/static/docs/command-reference/destroy.md
@@ -90,7 +90,7 @@ This will destroy all information about your pipelines, all data files...
 Are you sure you want to continue? [y/n]
 yes
 
- $ ls -a
+$ ls -a
 .git code.py foo
 ```
 
@@ -99,8 +99,8 @@ from the <abbr>workspace</abbr>. But the cache files that are present in the
 `/mnt/cache` directory still persist:
 
 ```dvc
- $ tree /mnt/cache
- /mnt/cache/
- └── b1
-     └── 946ac92492d2347c6235b4d2611184
+$ tree /mnt/cache
+/mnt/cache/
+└── b1
+    └── 946ac92492d2347c6235b4d2611184
 ```
diff --git a/static/docs/command-reference/import-url.md b/static/docs/command-reference/import-url.md
@@ -63,11 +63,15 @@ DVC supports several types of (local or) remote locations (protocols):
 > `[gs]`, `[azure]`, and `[oss]` (or `[all]` to include them all) when
 > [installing DVC](/doc/install) with `pip`.
 
+<!-- Separate MD quote: -->
+
 > In case of HTTP,
 > [strong ETag](https://en.wikipedia.org/wiki/HTTP_ETag#Strong_and_weak_validation)
 > is necessary to track if the specified remote file (URL) changed to download
 > it again.
 
+<!-- Separate MD quote: -->
+
 > `remote://myremote/path/to/file` notation just means that a DVC
 > [remote](/doc/command-reference/remote) `myremote` is defined and when DVC is
 > running. DVC automatically expands this URL into a regular S3, SSH, GS, etc
@@ -260,8 +264,8 @@ $ rm -f code.zip
 ### Click and expand to setup the environment
 
 Let's install the requirements. But before we do that, we **strongly** recommend
-creating a virtual environment with a tool such as
-[virtualenv](https://virtualenv.pypa.io/en/stable/):
+creating a
+[virtual environment](https://packaging.python.org/tutorials/installing-packages/#creating-virtual-environments):
 
 ```dvc
 $ virtualenv -p python3 .env

diff --git a/static/docs/command-reference/install.md b/static/docs/command-reference/install.md
@@ -100,8 +100,8 @@ $ cd example-get-started
 ```
 
 Now let's install the requirements. But before we do that, we **strongly**
-recommend creating a virtual environment with a tool such as
-[virtualenv](https://virtualenv.pypa.io/en/stable/):
+recommend creating a
+[virtual environment](https://packaging.python.org/tutorials/installing-packages/#creating-virtual-environments):
 
 ```dvc
 $ virtualenv -p python3 .env

diff --git a/static/docs/command-reference/pull.md b/static/docs/command-reference/pull.md
@@ -22,7 +22,7 @@ positional arguments:
 The `dvc pull` and `dvc push` commands are the means for uploading and
 downloading data to and from remote storage. These commands are analogous to the
 `git pull` and `git push` commands.
-[Data sharing](/doc/use-cases/share-data-and-model-files) across environments
+[Data sharing](/doc/use-cases/sharing-data-and-model-files) across environments
 and preserving data versions (input datasets, intermediate results, models,
 [metrics](/doc/command-reference/metrics), etc) remotely (S3, SSH, GCS, etc.)
 are the most common use cases for these commands.

diff --git a/static/docs/command-reference/push.md b/static/docs/command-reference/push.md
@@ -19,10 +19,11 @@ positional arguments:
 
 The `dvc push` command is the twin pair to the `dvc pull` command, and together
 they are the means for uploading and downloading data to and from remote
-storage, respectively. [Data sharing](/doc/use-cases/share-data-and-model-files)
-across environments and preserving data versions (input datasets, intermediate
-results, models, [metrics](/doc/command-reference/metrics), etc) remotely (S3,
-SSH, GCS, etc.) are the most common use cases for these commands.
+storage, respectively.
+[Data sharing](/doc/use-cases/sharing-data-and-model-files) across environments
+and preserving data versions (input datasets, intermediate results, models,
+[metrics](/doc/command-reference/metrics), etc) remotely (S3, SSH, GCS, etc.)
+are the most common use cases for these commands.
 
 The `dvc push` command allows one to upload data to remote storage. It doesn't
 save any changes in the code or DVC-files. Those should be saved by using

diff --git a/static/docs/command-reference/remote/index.md b/static/docs/command-reference/remote/index.md
@@ -56,7 +56,7 @@ enables basic DVC usage scenarios out of the box.
 be used or these files could be edited manually.
 
 For the typical process to share the <abbr>project</abbr> via remote, see
-[Share Data And Model Files](/doc/use-cases/share-data-and-model-files).
+[Sharing Data And Model Files](/doc/use-cases/sharing-data-and-model-files).
 
 ## Options
 

diff --git a/static/docs/command-reference/remote/modify.md b/static/docs/command-reference/remote/modify.md
@@ -269,8 +269,8 @@ For more information on configuring Azure Storage connection strings, visit
   [with kerberos](https://en.wikipedia.org/wiki/Generic_Security_Services_Application_Program_Interface#Relationship_to_Kerberos)).
   Using this option requires `paramiko[gssapi]`, which is currently only
   supported by our pip package, and could be installed with
-  `pip install 'dvc[ssh_gssapi]'`. Other packages (Conda, Windows and Mac pkg)
-  do not support it.
+  `pip install 'dvc[ssh_gssapi]'`. Other packages (Conda, Windows, and MacOS
+  PKG) do not support it.
 
   ```dvc
   $ dvc remote modify myremote gss_auth true

diff --git a/static/docs/command-reference/remove.md b/static/docs/command-reference/remove.md
@@ -22,8 +22,8 @@ Note that it does not remove files from the DVC cache or remote storage (see
 `dvc gc`). However, remember to run `dvc push` to save the files you actually
 want to use or share in the future.
 
-Refer to [Update Tracked Files](/doc/user-guide/update-tracked-files) to see how
-it can be used to replace or modify files that are under DVC control.
+Refer to [Updating Tracked Files](/doc/user-guide/updating-tracked-files) to see
+how it can be used to replace or modify files that are under DVC control.
 
 ## Options
 

diff --git a/static/docs/command-reference/status.md b/static/docs/command-reference/status.md
@@ -94,7 +94,7 @@ outputs described in it.
 For either _new_ and _deleted_ data, the cache (subset determined by the current
 workspace) is different from remote storage. Bringing the two into sync requires
 `dvc pull` or `dvc push`. For the typical process to update the workspace, see
-[Share Data And Model Files](/doc/use-cases/share-data-and-model-files).
+[Sharing Data And Model Files](/doc/use-cases/sharing-data-and-model-files).
 
 ## Options
 

diff --git a/static/docs/command-reference/unprotect.md b/static/docs/command-reference/unprotect.md
@@ -26,7 +26,7 @@ prevent users from accidentally corrupting the cache by modifying file links.)
 Running `dvc unprotect` guarantees that the target files or directories
 (`targets`) in the workspace are physically "unlinked" from the cache and can be
 safely updated. Read the
-[Update a Tracked File](/doc/user-guide/update-tracked-files) guide to learn
+[Update a Tracked File](/doc/user-guide/updating-tracked-files) guide to learn
 more on this process.
 
 `dvc unprotect` can be an expensive operation (involves copying data). Check

diff --git a/static/docs/command-reference/version.md b/static/docs/command-reference/version.md
@@ -26,6 +26,8 @@ system/environment:
 > If `dvc version` is executed outside a DVC project, no `Cache` is output and
 > the `Filesystem type` output is of the current working directory.
 
+<!-- Separate MD quote: -->
+
 > **Note** that if you've installed dvc using pip, you will need to install
 > `psutil` by yourself with `pip install psutil` in order for `dvc version` to
 > report file system information. Please see the original
@@ -38,8 +40,10 @@ The detail of DVC version depends upon the way of installing DVC.
 - **Official release**: [These instructions](/doc/install) include ways to
   install DVC using the official package stored in Python Packaging Authority.
   We mark these official releases with tags on DVC's repository. Any issues
-  reported with the official build can be traced using the `BASE_VERSION`
-  itself. So the output is simply `0.40.2`.
+  reported with the official build can be traced using the `_BASE_VERSION`
+  constant
+  [in our core repo](https://github.com/iterative/dvc/blob/master/dvc/version.py).
+  For example `0.40.2`.
 
 - **Development version**: `pip install git+git://github.com/iterative/dvc` will
   install DVC using the `master` branch of DVC's repository. Another way of
@@ -49,13 +53,13 @@ The detail of DVC version depends upon the way of installing DVC.
   command might have issues regarding its usage. So to trace any error reported
   with this setup, we need to know exactly which version is being used. For this
   we rely on a git commit hash that is displayed in this command's output like
-  this: `0.40.2+292cab.mod`. The part before `+` is the `BASE_VERSION` and the
-  latter part is the `master` branch commit hash. The optional suffix `.mod`
-  means that code is modified.
+  this: `0.40.2+292cab.mod`. The part before `+` is the `_BASE_VERSION`, and the
+  following part is the latest `master` branch commit hash. The optional suffix
+  `.mod` means that code is modified.
 
 #### What we mean by "Binary"
 
-The detail of `Binary` depends on the way DVC was downloading and
+The detail of `Binary` depends on the way DVC was downloaded and
 [installed](/doc/install).
 
 - **`Binary: True`** - displayed when DVC is downloaded/installed as one of:
@@ -70,8 +74,9 @@ The detail of `Binary` depends on the way DVC was downloading and
   These downloads are available from our [home page](/). They ultimately contain
   a binary bundle, which is the executable file of a software application,
   meaning that it will run natively on a specific platform (Linux, Windows,
-  Mac). In our case, we use [PyInstaller](https://pythonhosted.org/PyInstaller/)
-  to bundle our source code into the binary package app.
+  MacOS). In our case, we use
+  [PyInstaller](https://pythonhosted.org/PyInstaller/) to bundle our source code
+  into the binary package app.
 
 - **`Binary: False`** - shown when DVC is downloaded and installed from:
 

diff --git a/static/docs/get-started/add-files.md b/static/docs/get-started/add-files.md
@@ -83,6 +83,6 @@ will go under its control automatically takes care of this for you! (You just
 have to add the changes with Git.)
 
 Refer to
-[Data and Model Files Versioning](/doc/use-cases/data-and-model-files-versioning),
+[Versioning Data and Model Files](/doc/use-cases/versioning-data-and-model-files),
 `dvc add`, and `dvc run` for more information on storing and versioning data
 files with DVC.
diff --git a/static/docs/get-started/connect-code-and-data.md b/static/docs/get-started/connect-code-and-data.md
@@ -19,7 +19,10 @@ $ unzip code.zip
 $ rm -f code.zip
 ```
 
-> On Windows just use your browser to download the archive instead.
+Windows doesn't include the `wget` utility by default, but you can use the
+browser to download `code.zip`. (Right-click
+[this link](https://code.dvc.org/get-started/code.zip) and select
+`Save Link As...` (Chrome). Save it into the project directory.
 
 The workspace should now look like this:
 
@@ -38,8 +41,8 @@ $ tree
 ```
 
 Now let's install the requirements. But before we do that, we **strongly**
-recommend creating a virtual environment with a tool such as
-[virtualenv](https://virtualenv.pypa.io/en/stable/):
+recommend creating a
+[virtual environment](https://packaging.python.org/tutorials/installing-packages/#creating-virtual-environments):
 
 ```dvc
 $ virtualenv -p python3 .env

diff --git a/static/docs/get-started/initialize.md b/static/docs/get-started/initialize.md
@@ -1,22 +1,16 @@
 # Initialize
 
 There are a few recommended ways to install DVC: OS-specific package/installer,
-`pip`, `conda`, and Homebrew. See the **[installation](/doc/install)** page for
+`pip`, `conda`, and Homebrew. See the [**Installation**](/doc/install) page for
 all the options and details.
 
-In order to start using DVC, you need first to initialize it in your
-<abbr>workspace</abbr>, but let's prepare it first:
+Let's start by creating a <abbr>workspace</abbr> we can version with Git. Then
+run `dvc init` inside to create the DVC <abbr>project</abbr>:
 
 ```dvc
 $ mkdir example-get-started
 $ cd example-get-started
 $ git init
-```
-
-Run DVC initialization in a repository directory to create the DVC meta files
-and directories:
-
-```dvc
 $ dvc init
 $ git commit -m "Initialize DVC project"
 ```

diff --git a/static/docs/get-started/retrieve-data.md b/static/docs/get-started/retrieve-data.md
@@ -29,5 +29,5 @@ $ dvc pull data/data.xml.dvc
 
 DVC remotes, `dvc push`, and `dvc pull` provide a basic collaboration workflow,
 the same way as Git remotes, `git push` and `git pull`. See
-[Share Data and Model Files](/doc/use-cases/share-data-and-model-files) for more
-information.
+[Sharing Data and Model Files](/doc/use-cases/sharing-data-and-model-files) for
+more information.
diff --git a/static/docs/install/completion.md b/static/docs/install/completion.md
@@ -2,6 +2,11 @@
 
 Enjoy working with DVC faster and with fewer typos!
 
+Shell completion is automatically enabled when DVC is installed on MacOS
+[with Homebrew](/doc/install/macos#install-with-brew), or on Linux
+[from **deb** or **rpm** repository](/doc/install/linux#install-from-repository).
+Please follow the instructions below for other DVC installation methods.
+
 ## How it works
 
 Command completion is usually requested by pressing the `tab` key on your shell,
@@ -27,15 +32,15 @@ Depending on what you typed on the command line so far, it completes:
 - Arguments for selected options. For example, `dvc repro` completes with stage
   files to reproduce.
 
-## Which shell you have
+## What shell do you have?
 
 Use the command `echo $0` to check your active shell, if you are not sure which
 one you are using (Bash or Zsh).
 
 Depending on the shell that you are using, follow the instruction below to
 install and configure shell completion.
 
-## Bash completion on Mac OS
+## Bash completion on MacOS
 
 1. First, make sure that Bash completion support is installed:
 
@@ -63,7 +68,7 @@ install and configure shell completion.
 
 4. Finally, `source ~/.bash_profile` or launch a new terminal to activate it.
 
-## Bash completion on Ubuntu
+## Bash completion on Debian/Ubuntu
 
 1. First, make sure that Bash completion support is installed:
 

diff --git a/static/docs/install/index.md b/static/docs/install/index.md
@@ -3,12 +3,18 @@
 Please double check that you don't already have DVC (for example running
 `which dvc`) before trying to install it (again).
 
-- [Install on Mac OS](/doc/install/macos)
+- [Install on MacOS](/doc/install/macos)
 - [Install on Windows](/doc/install/windows)
 - [Install on Linux](/doc/install/linux)
 
-You can also [install the development version](/doc/install/pre-release), before
-the official release.
+## Advanced options
 
-It is recommended to setup [shell completion](/doc/install/completion) as well.
-And check out these [plugins](/doc/install/plugins), which might be useful too.
+- Shell completion is automatically enabled by certain installation methods. If
+  it does not work for you, please see
+  [these instructions](/doc/install/completion) to set it up.
+
+- You can [install a stable pre-release](/doc/install/pre-release) of DVC to
+  stay ahead of official releases.
+
+- Please also check out these 3rd-party tool
+  [plugins](/doc/user-guide/install/plugins), which might be useful.
diff --git a/static/docs/install/linux.md b/static/docs/install/linux.md
@@ -6,7 +6,7 @@
 > [virtual environment](https://packaging.python.org/tutorials/installing-packages/#creating-virtual-environments)
 > or
 > [pipx](https://packaging.python.org/guides/installing-stand-alone-command-line-tools/)
-> for Python 3.6+ to keep your system environment safe.
+> (on Python 3.6+) to encapsulate your local environment.
 
 ```dvc
 $ pip install dvc