how-to: further improvements

content/docs/sidebar.json

@@ -88,7 +88,6 @@
         "source": "what-is-dvc.md"
       },
       "dvc-files-and-directories",
-      "merge-conflicts",
       {
         "slug": "dvcignore",
         "tutorials": {
@@ -101,8 +100,9 @@
         "source": false,
         "children": [
           "stop-tracking-data",
-          "update-tracked-files",
-          "add-deps-or-outs-to-a-stage"
+          "update-tracked-data",
+          "add-deps-or-outs-to-a-stage",
+          "merge-conflicts"
         ]
       },
       "setup-google-drive-remote",

content/docs/user-guide/how-to/add-deps-or-outs-to-a-stage.md

@@ -1,20 +1,21 @@
 ---
-title: 'How to Add Dependencies or Outputs to a Stage '
-description: 'We have executed a stage, but later notice that some of the
-dependencies or outputs are missing...'
+title: 'How to Add Dependencies or Outputs to a Stage'
+description: 'It's possible to add files or directories to existing stages, with
+or without executing them.'
 ---
 
 # How to Add Dependencies or Outputs
 
-To add <abbr>dependencies</abbr> or <abbr>outputs</abbr> to a stage, edit the
-`dvc.yaml` file (by hand or using `dvc run` with the `-f --no-exec` flags).
-`dvc repro` will execute it and <abbr>cache</abbr> the output files when ready.
+To add <abbr>dependencies</abbr> or <abbr>outputs</abbr> to a
+[stage](/doc/command-reference/run), edit the `dvc.yaml` file (by hand or using
+`dvc run` with the `-f --no-exec` flags). `dvc repro` will execute it and
+<abbr>cache</abbr> the output files when ready.
 
 If the stage has already been executed it and the desired outputs are present in
 the <abbr>workspace</abbr>, you can avoid `dvc repro` (which can be expensive
 and is unnecessary) and use `dvc commit` instead.
 
-> Both alternatives update `dvc.lock` accordingly.
+> Note that both alternatives update `dvc.lock` too.
 
 ## Example
 

content/docs/user-guide/merge-conflicts.md → content/docs/user-guide/how-to/merge-conflicts.md

@@ -1,8 +1,14 @@
-# Merge Conflicts
+---
+title: 'How to Merge Conflicts'
+description: 'Git merge conflicts can happen in in DVC metafiles when combining
+changes from multiple team members.'
+---
+
+# How to Merge Conflicts in DVC Metafiles
 
 Sometimes multiple members of a team might work on the the same DVC-tracked
 data. And when the time comes to combine their changes, merge conflicts can
-arise in Git-tracked [metafiles](/doc/user-guide/dvc-files-and-directories),
+happen in Git-tracked [metafiles](/doc/user-guide/dvc-files-and-directories),
 which need to be resolved.
 
 ## `dvc.yaml`

content/docs/user-guide/how-to/stop-tracking-data.md

@@ -0,0 +1,48 @@
+---
+title: 'How to Stop Tracking Data'
+description: 'You can "un-track" files or directories added in error.'
+---
+
+# How to Stop Tracking Data
+
+There are situations where you may want to "un-track" files or directories added
+in error to DVC.
+
+<details>
+
+## Expand to add a sample data `data.csv` file
+
+`dvc add` creates a `.dvc` file to track the file, and lists it in `.gitignore`:
+
+```dvc
+$ dvc add data.csv
+
+$ ls
+data.csv    data.csv.dvc
+$ cat .gitignore
+/data.csv
+```
+
+</details>
+
+Let's undo `dvc add` with `dvc remove`. This deletes the `.dvc` file (and
+corresponding `.gitignore` entry). The data file is now no longer being tracked
+after this:
+
+```dvc
+$ dvc remove data.csv.dvc
+
+$ git status
+    Untracked files:
+        data.csv
+```
+
+You can run `dvc gc` with the `-w` option to remove the data (and all of it's
+previous versions, if any) from the <abbr>cache</abbr>:
+
+```dvc
+$ dvc gc -w
+```
+
+> Note that a very similar procedure works for `dvc.yaml` stages and their
+> outputs.

content/docs/user-guide/how-to/update-tracked-files.md → content/docs/user-guide/how-to/update-tracked-data.md

@@ -1,8 +1,14 @@
-# How to Update Tracked Files
+---
+title: 'How to Update Tracked Data'
+description: 'Updating files or directories may mean either modifying some of
+the data contents, or completely replacing them.'
+---
 
-Updating a tracked data file (or directory) may mean either
-[modifying](#modifying-content) some of its contents, or completely
-[replacing](#replacing-file) it with a new one (same file name).
+# How to Update Tracked Data
+
+Updating tracked files or directories may mean either
+[modifying](#modifying-content) some of the data contents, or completely
+[replacing](#replacing-file) them (under the same file name).
 
 When the `cache.type` config option is set to `symlink` or `hardlink` (not the
 default, see `dvc config cache` for more info.), updating tracked files has to

redirects-list.json

@@ -29,7 +29,9 @@
 
   "^/doc/use-cases/data-and-model-files-versioning/?$                                     /doc/use-cases/versioning-data-and-model-files",
   "^/doc/user-guide/dvc-file-format$                                                      /doc/user-guide/dvc-files-and-directories",
-  "^/doc/user-guide/updating-tracked-files$                                               /doc/user-guide/how-to/update-tracked-files",
+  "^/doc/user-guide/updating-tracked-files$                                               /doc/user-guide/how-to/update-tracked-data",
+  "^/doc/user-guide/how-to/update-tracked-files$                                          /doc/user-guide/how-to/update-tracked-data",
+  "^/doc/user-guide/merge-conflicts$                                                      /doc/user-guide/how-to/merge-conflicts",
   "^/doc/understanding-dvc(/.*)?$                                                         /doc/user-guide/what-is-dvc",
   "^/doc/commands-reference(/.*)?$                                                        /doc/command-reference$1",
   "^/doc/command-reference/plot$                                                          /doc/command-reference/plots",