ref: update exp run reference for queue changes

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

@@ -27,8 +27,12 @@ With `--queue`, the list of experiments awaiting execution is cleared instead.
 - `--queue` - remove all experiments that haven't been run yet (defined via
   `dvc exp run --queue`).
 
-- `-A`, `--all` - remove all experiments that have been run. Use `--queue` to
-  remove queued ones.
+  > ⚠️ `dvc exp remove --queue` is now an alias for `dvc queue remove --queued`.
+  > The `--queue` option will likely be deprecated and removed in a future DVC
+  > release. Refer to the `dvc queue` documentation for more details.
+
+- `-A`, `--all` - remove all experiments that have been run. Use
+  `dvc queue remove` to remove queued experiment tasks.
 
 - `--rev <commit>` - remove experiments derived from the specified `<commit>` as
   baseline.

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

@@ -34,13 +34,9 @@ Use the `--set-param` (`-S`) option as a shortcut to change
 <abbr>parameter</abbr> values [on-the-fly] before running the experiment.
 
 It's possible to [queue experiments] for later execution with the `--queue`
-flag. To actually run them, use `dvc exp run --run-all`. Queued experiments are
-run sequentially by default, but can be run in parallel using the `--jobs`
-option.
-
-> ⚠️ Parallel runs are experimental and may be unstable. Make sure you're using
-> a number of jobs that your environment can handle (no more than the CPU
-> cores).
+flag. Queued experiments can be run using `dvc queue start`, refer to th
+`dvc queue` documentation for more information on managing the experiment task
+queue.
 
 It's also possible to run special [checkpoint experiments] that log the
 execution progress (useful for deep learning ML). The `--rev` and `--reset`
@@ -82,8 +78,7 @@ committing them to the Git repo. Unnecessary ones can be [cleared] with
   runs.
 
 - `--queue` - place this experiment at the end of a line for future execution,
-  but don't actually run it yet. Use `dvc exp run --run-all` to process the
-  queue.
+  but don't actually run it yet. Use `dvc queue start` to process the queue.
 
   > For checkpoint experiments, this implies `--reset` unless a `--rev` is
   > provided.
@@ -100,6 +95,13 @@ committing them to the Git repo. Unnecessary ones can be [cleared] with
   > stages may sometimes be executed several times depending on the state of the
   > [run-cache] at that time.
 
+  > ⚠️ `dvc exp run --run-all [--jobs]` is now a shortcut for
+  > `dvc queue start [--jobs]` followed by `dvc queue logs -f`. The `--run-all`
+  > and `--jobs` options will likely be deprecated and removed in a future DVC
+  > release. It is recommended to migrate your workflows to use
+  > `dvc queue start` and `dvc queue logs`. Refer to the `dvc queue`
+  > documentation for more details.
+
 - `-r <commit>`, `--rev <commit>` - resume an experiment from a specific
   checkpoint name or hash (`commit`) in `--queue` or `--temp` runs.
 

content/docs/command-reference/queue/start.md

@@ -28,6 +28,10 @@ the `--jobs` option.
 > a number of jobs that your environment can handle (no more than the CPU
 > cores).
 
+> Note that since queued experiments are run isolated from each other, common
+> stages may sometimes be executed several times depending on the state of the
+> [run-cache] at that time.
+
 ## Options
 
 - `-j <number>`, `--<number>` - start up to this number of workers in parallel.

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

@@ -116,23 +116,23 @@ Queued experiment '4109ead' for future execution.
 
 ### How are experiments queued?
 
-Queued experiments are created similar to
-[Git stash](https://www.git-scm.com/docs/git-stash). The last experiment queued
-is found in `.git/refs/exps`, and earlier ones are in its [reflog].
+Queued experiments are managed using [dvc-task] and [Celery].
 
-[reflog]:
-  https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefreflogareflog
+[dvc-task]: https://github.com/iterative/dvc-task
+[celery]: https://docs.celeryq.dev/en/stable/index.html
 
 </details>
 
-Run them all with the `--run-all` flag:
+Run them all with `dvc queue start`:
 
 ```dvc
-$ dvc exp run --run-all
+$ dvc queue start
 ...
 ```
 
-> Note that the order of execution is independent of their creation order.
+> Note that in most cases, experiment tasks will be executed in the order that
+> they were added to the queue (First In, First Out), but this order is not
+> guaranteed due to Celery limitations.
 
 Their execution happens outside your <abbr>workspace</abbr> in temporary
 directories for isolation, so each experiment is derived from the workspace at
@@ -164,10 +164,11 @@ committing unwanted files into Git (e.g. once successful experiments are
 
 </details>
 
-💡 To clear the experiments queue and start over, use `dvc exp remove --queue`.
+💡 To clear the experiments queue and start over, use
+`dvc queue remove --queued`.
 
-> 📖 See the `dvc exp run` reference for more options related to experiments
-> queue, such as running them in parallel with `--jobs`.
+> 📖 See the `dvc exp run` and `dvc queue` references for more options related
+> to the experiments queue, such as running them in parallel with `--jobs`.
 
 ## Checkpoint experiments