exp: misc. guide and ref. updates

content/docs/command-reference/exp/apply.md

@@ -14,22 +14,25 @@ positional arguments:
 
 ## Description
 
-Restores an `experiment` into the workspace as long as no more Git commits have
-been made after the target experiment (`HEAD` hasn't moved). The `experiment`
-can be referenced by name or hash (see `dvc exp run` for details). This changes
-any files (code, data, <abbr>parameters</abbr>, <abbr>metrics</abbr>, etc.)
-needed to reflect the experiment conditions and results in the workspace.
+Restores an `experiment` into the workspace, as long as we're on the same
+project baseline (Git `HEAD`) as when the target experiment was run. The
+experiment can be referenced by name or hash (see `dvc exp run` for details).
 
-⚠️ Conflicting changes in the workspace are overwritten unless `--no-force` is
-used.
+Specifically, `dvc exp apply` checks out any files or directories needed to
+reflect the experiment conditions and results. This can include both with DVC
+and Git: code, data, <abbr>parameters</abbr>, <abbr>metrics</abbr>, etc.
+
+⚠️ This command will destroy any existing changes in the workspace (Git working
+tree) unless the `--no-force` flag is used.
 
 This is typically used after choosing a target `experiment` with `dvc exp show`
-or `dvc exp diff`, and before committing it to Git (making it
-[persistent](/doc/user-guide/experiment-management#persistent-experiments)).
+or `dvc exp diff`, and before committing it to Git (making it [persistent].
+
+> Note that if a history of [checkpoints] is found in the `experiment`, it will
+> **not** be preserved when applying and committing it.
 
-Note that the history of
-[checkpoints](/doc/command-reference/exp/run#checkpoints) found in the
-`experiment` is **not** preserved when applying and committing it.
+[persistent]: /doc/user-guide/experiment-management/persisting-experiments
+[checkpoints]: /doc/user-guide/experiment-management/checkpoints
 
 ## Options
 

content/docs/command-reference/exp/branch.md

@@ -15,26 +15,28 @@ positional arguments:
 
 ## Description
 
-Makes a named Git
-[`branch`](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging)
-containing the target `experiment` (making it
-[persistent](/doc/user-guide/experiment-management#persistent-experiments)). For
-[checkpoint experiments](/doc/command-reference/exp/run#checkpoints), the new
-branch will contain multiple commits (the checkpoints).
+Makes a given Git [`branch`] containing the target `experiment`. This makes the
+experiment into a [regular commit], or several in the case of [checkpoint
+experiments] (one per checkpoint).
 
 The new `branch` will be based on the experiment's parent commit (`HEAD` at the
 time that the experiment was run). Note that DVC **does not** switch into the
 new `branch` automatically.
 
 `dvc exp branch` is useful to make an experiment persistent without modifying
-the workspace, so they can be continued,
-[stored, and shared](https://dvc.org/doc/use-cases/sharing-data-and-model-files)
-in a normal Git + DVC workflow.
+the workspace, so they can be continued, [stored and shared] in a normal Git +
+DVC workflow.
 
 To switch into the new branch, use `git checkout branch` and `dvc checkout`. Or
 use `git merge branch` and `dvc repro` to combine it with your current project
 version.
 
+[`branch`]:
+  https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging
+[regular commit]: /doc/user-guide/experiment-management/persisting-experiments
+[checkpoint experiments]: /doc/command-reference/exp/run#checkpoints
+[stored and shared]: /doc/use-cases/sharing-data-and-model-files
+
 ## Options
 
 - `-h`, `--help` - shows the help message and exit.

content/docs/command-reference/exp/run.md

@@ -44,7 +44,7 @@ name like `exp-bfe64` by default, which can be customized using the `--name`
 Experiments are custom
 [Git references](https://git-scm.com/book/en/v2/Git-Internals-Git-References)
 (found in `.git/refs/exps`) with a single commit based on `HEAD` (not checked
-out by DVC). Note that these commits are not pushed to the Git remote by default
+out by DVC). Note that these commits are not pushed to Git remotes by default
 (see `dvc exp push`).
 
 </details>

content/docs/sidebar.json

@@ -132,18 +132,6 @@
           }
         ]
       },
-      {
-        "label": "How To",
-        "slug": "how-to",
-        "source": false,
-        "children": [
-          "stop-tracking-data",
-          "update-tracked-data",
-          "add-deps-or-outs-to-a-stage",
-          "merge-conflicts",
-          "share-a-dvc-cache"
-        ]
-      },
       {
         "label": "Experiment Management",
         "slug": "experiment-management",
@@ -158,6 +146,18 @@
           "checkpoints"
         ]
       },
+      {
+        "slug": "how-to",
+        "source": false,
+        "children": [
+          "stop-tracking-data",
+          "update-tracked-data",
+          "add-deps-or-outs-to-a-stage",
+          "merge-conflicts",
+          "share-a-dvc-cache",
+          "share-many-experiments"
+        ]
+      },
       "setup-google-drive-remote",
       "large-dataset-optimization",
       "external-dependencies",

content/docs/user-guide/experiment-management/comparing-experiments.md

@@ -384,8 +384,8 @@ params.yaml  train.epochs      10    10         0
 ## Compare an experiment with the workspace
 
 When you want to compare two experiments, either the baseline experiment in a
-commit, branch, tag or an attached experiment with ID, you can supply their
-names to `dvc exp diff`.
+commit, branch, or tag; or an attached experiment by name, you can supply any of
+these references to `dvc exp diff`.
 
 ```
 $ dvc exp diff cnn-128 cnn-64

content/docs/user-guide/experiment-management/index.md

@@ -47,8 +47,8 @@ main alternatives:
 
 - **Git tags and branches** - use the repo's "time dimension" to distribute your
   experiments. This makes the most sense for experiments that build on each
-  other. Helpful if the Git [revisions](https://git-scm.com/docs/revisions) can
-  be easily visualized, for example with tools
+  other. Git-based experiment structures are especially helpful along with Git
+  history exploration tools
   [like GitHub](https://docs.github.com/en/github/visualizing-repository-data-with-graphs/viewing-a-repositorys-network).
 
 - **Directories** - the project's "space dimension" can be structured with

content/docs/user-guide/project-structure/internal-files.md

@@ -134,7 +134,7 @@ $ cat .dvc/cache/6f/db5336fce0dbfd669f83065f107551.dir
 
 That's how DVC knows that the other two cached files belong in the directory.
 
-### Run-cache
+## Run-cache
 
 `dvc exp run` and `dvc repro` by default populate and reutilize a log of stages
 that have been run in the project. It is found in the `runs/` directory inside

content/docs/user-guide/troubleshooting.md

@@ -92,16 +92,17 @@ using:
 $ dvc checkout --relink
 ```
 
-## HTTP Git authentication is not supported {#git-auth}
+## DVC can only authenticate with Git remotes using SSH URLs {#git-auth}
 
 [Experiment sharing](/doc/user-guide/experiment-management/sharing-experiments)
-commands accept a `git_remote` argument. In order to access the Git remote, you
-may need to authenticate for _write_ (`dvc exp push`) or _read_ (`dvc exp list`,
+commands accept a `git_remote` argument. You may need to authenticate to use the
+Git remote, for _write_ (`dvc exp push`) or _read_ (`dvc exp list`,
 `dvc exp pull`) permissions.
 
 DVC does not currently support authentication with [Git credentials]. This means
 that unless the Git server allows unauthenticated HTTP write/read, you should
-use an [SSH Git URL] when listing, pulling or pushing experiments.
+use an [SSH Git URL] for Git remotes used for listing, pulling or pushing
+experiments.
 
 [git credentials]: https://git-scm.com/docs/gitcredentials
 [ssh git url]: