guide: reorder how-tos and copy edits; expand on adding existing dependencies to a stage

content/docs/command-reference/commit.md

@@ -42,10 +42,10 @@ scenarios are further detailed below.
 
 - In cases where we have previously executed a stage (either by writing
   `dvc.yaml` manually and using `dvc repro`, or with `dvc run`), but later
-  notice that some of the output files or directories it creates, which are
-  already in the <abbr>workspace</abbr>, are missing from `dvc.yaml` (`outs`
-  field). We can
-  [add missing outputs to an existing stage](/docs/user-guide/how-to/add-output-to-stage)
+  notice that some of the existing dependencies, or output files/directories it
+  creates, which are already in the <abbr>workspace</abbr>, are missing from
+  `dvc.yaml` (`deps` and `outs` field respectively). We can
+  [add missing dependencies/outputs to an existing stage](/docs/user-guide/how-to/add-deps-or-outs-to-a-stage)
   without having to execute it again. Use `dvc commit` to update the `dvc.lock`
   file and save outputs to the cache.
 

content/docs/command-reference/run.md

@@ -107,9 +107,10 @@ Relevant notes:
   defined as outputs every time its executed by DVC.
 
 - In some situations we have executed a stage and later notice that some of the
-  output files or directories it creates, which are already in the workspace,
-  are missing from `dvc.yaml` (`outs` field). We can
-  [add missing outputs to an existing stage](/docs/user-guide/how-to/add-output-to-stage)
+  existing dependencies, or output files/directories it creates, which are
+  already in the workspace, are missing from `dvc.yaml` (`deps` and `outs` field
+  respectively). We can
+  [add missing dependencies/outputs to an existing stage](/docs/user-guide/how-to/add-deps-or-outs-to-a-stage)
   without having to execute it again.
 
 - Renaming dependencies or outputs requires a

content/docs/sidebar.json

@@ -100,8 +100,11 @@
         "slug": "how-to",
         "source": false,
         "children": [
-          "add-output-to-stage",
           "undo-adding-data",
+        {
+          "label": "Add Tracked Data to a Stage",
+          "slug": "add-deps-or-outs-to-a-stage"
+        },
           "update-tracked-files"
         ]
       },

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

@@ -0,0 +1,56 @@
+# Add Dependencies or Outputs to a Stage
+
+There are situations where we have executed a stage (either by writing
+`dvc.yaml` manually and using `dvc repro`, or with `dvc run`), but later notice
+that some of the build requirements are missing from `dvc.yaml`:
+
+- Files or directories in the <abbr>workspace</abbr> that are dependencies of
+  the stage, are missing from `deps` field.
+
+- Output files or directories that the stage creates, which are already in the
+  workspace, are missing from `outs` field.
+
+Follow the steps below to add existing files/directories as
+<abbr>dependencies</abbr> or <abbr>outputs</abbr> to a stage without
+re-executing it again, which can be expensive/time-consuming, and is
+unnecessary.
+
+We start with an example `prepare`, which has a single dependency and output. To
+add a missing dependency `data.csv`, and output `data/validate` to this stage,
+we can edit `dvc.yaml` like this:
+
+```git
+ stages:
+   prepare:
+     cmd: python src/prepare.py
+     deps:
++    - data.csv
+     - src/prepare.py
+     outs:
+     - data/train
++    - data/validate
+```
+
+> Note that you can also use `dvc run` with the `-f` and `--no-exec` options to
+> add another dependency/output to the stage:
+>
+> ```dvc
+> $ dvc run -f --no-exec \
+>           -n prepare \
+>           -d data.csv \
+>           -d src/prepare.py \
+>           -o data/train \
+>           -o data/validate \
+>           python src/prepare.py
+> ```
+>
+> `-f` overwrites the stage in `dvc.yaml`, while `--no-exec` updates the stage
+> without executing it.
+
+Finally, we need to run `dvc commit` to save the newly specified output(s) to
+the <abbr>cache</abbr> (and to update the hash values of `deps` and `outs` in
+`dvc.lock`):
+
+```dvc
+$ dvc commit
+```

content/docs/user-guide/how-to/undo-adding-data.md

@@ -3,41 +3,33 @@
 There are situations where you want to stop tracking data added previously.
 Follow the steps listed here to undo `dvc add`.
 
-Let's first add a data file into an example <abbr>project</abbr> using
-`dvc add`, which creates a `.dvc` file to track the data:
+Let's first add a data file into an example <abbr>project</abbr>, which creates
+a `.dvc` file to track the data:
 
 ```dvc
 $ dvc add data.csv
 $ ls
 data.csv    data.csv.dvc
 ```
 
-> Note, if you are using `symlink` or `hardlink` as
-> [link type](/doc/user-guide/large-dataset-optimization#file-link-types-for-the-dvc-cache)
-> for DVC <abbr>cache</abbr>, you will have to unprotect the tracked file first
-> (see `dvc unprotect`):
->
-> ```dvc
-> $ dvc unprotect data.csv
-> ```
+> Note, if you're using `symlink` or `hardlink` as the project's
+> [link type](/doc/user-guide/large-dataset-optimization#file-link-types-for-the-dvc-cache),
+> you'll have to unprotect the tracked file first (see `dvc unprotect`).
 
-Now let's reverse `dvc add` by removing the corresponding `.dvc` file and
-`.gitignore` entry using `dvc remove`:
+Now let's reverse that with `dvc remove`. This removes the `.dvc` file (and
+corresponding `.gitignore` entry). The data file is now no longer being tracked
+after this:
 
 ```dvc
 $ dvc remove data.csv.dvc
-```
-
-Data file `data.csv` is now no longer being tracked by DVC.
 
-```dvc
 $ git status
     Untracked files:
         data.csv
 ```
 
 You can run `dvc gc` with the `-w` option to remove the data that isn't
-referenced in the current workspace from the cache:
+referenced in the current workspace from the <abbr>cache</abbr>:
 
 ```dvc
 $ dvc gc -w

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

@@ -1,4 +1,4 @@
-# Updating Tracked Files
+# Update Tracked Files
 
 Due to the way DVC handles linking between the data files between the
 <abbr>cache</abbr> and their counterparts in the <abbr>workspace</abbr> (refer