Rearrange swarming debug doc and add a concrete example.

- Move run-swarmed and mb.py to the top of the doc

This is a great doc but after working through a lot of steps, I found
that I could have just run mb.py. So this adds a "The easy way"
section at the top of the doc and moves the combined tools to that.

- Factor out the authentication section so that it's linkable.

- Add a concrete example and advice on how to construct $criteria.

Change-Id: I0e7dcbcf9ce38aeed08a614e35f3f1374d2fa8c8
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/1871158Reviewed-by: Elly Fong-Jones <ellyjones@chromium.org>
Commit-Queue: Fergal Daly <fergal@chromium.org>
Cr-Commit-Position: refs/heads/master@{#707793}

docs/workflow/debugging-with-swarming.md

@@ -54,6 +54,80 @@ or perhaps:
   use_swarming_to_run(type, isolate)
 ```
 
+## The easy way
+
+A lot of the steps described in this doc have been bundled up into 2
+tools. Before using either of these you will need to
+[authenticate](#authenticating).
+
+### run-swarmed.py
+
+A lot of the logic below is wrapped up in `tools/run-swarmed.py`, which you can run
+like this:
+
+```
+$ tools/run-swarmed.py $outdir $target
+```
+
+See the `--help` option of `run-swarmed.py` for more details about that script.
+
+### mb.py run
+
+Similar to `tools/run_swarmed.py`, `mb.py run` bundles much of the logic into a
+single command line. Unlike `tools/run_swarmed.py`, `mb.py run` allows the user
+to specify extra arguments to pass to the test, but has a messier command line.
+
+To use it, run:
+```
+$ tools/mb/mb.py run \
+    -s --no-default-dimensions \
+    -d pool $pool \
+    $criteria \
+    $outdir $target \
+    -- $extra_args
+```
+
+## A concrete example
+
+Here's how to run `chrome_public_test_apk` on a bot with a Nexus 5 running KitKat.
+
+```sh
+$ tools/mb/mb.py run \
+    -s --no-default-dimensions \
+    -d pool Chrome \
+    -d device_os_type userdebug -d device_os KTU84P -d device_type hammerhead \
+    out/Android-arm-dbg chrome_public_test_apk
+```
+
+This assumes you have an `out/Android-arm-dbg/args.gn` like
+
+```
+ffmpeg_branding = "Chrome"
+is_component_build = false
+is_debug = true
+proprietary_codecs = true
+strip_absolute_paths_from_debug_symbols = true
+symbol_level = 1
+system_webview_package_name = "com.google.android.webview"
+target_os = "android"
+use_goma = true
+```
+
+## Bot selection criteria
+
+The examples in this doc use `$criteria`. To figure out what values to use, you
+can go to an existing swarming run
+([recent tasks page](https://chromium-swarm.appspot.com/tasklist)) and
+look at the `Dimensions` section. Each of these becomes a `-d dimension_name
+dimension_value` in your `$criteria`. Click on `bots` (or go
+[here](https://chromium-swarm.appspot.com/botlist)) to be taken to a UI that
+allows you to try out the criteria interactively, so that you can be sure that
+there are bots matching your criteria. Sometimes the web page shows a
+human-friendly name rather than the name required on the commandline. [This
+file](https://cs.chromium.org/chromium/infra/luci/appengine/swarming/ui2/modules/alias.js)
+contains the mapping to human-friendly names. You can test your commandline by
+entering `dimension_name:dimension_value` in the interactive UI.
+
 ## Building an isolate
 
 At the moment, you can only build an isolate locally, like so (commands you type
@@ -74,6 +148,17 @@ $ tools/mb/mb.py isolate --no-build //$outdir $target
 Support for building an isolate using swarming, which would allow you to build
 for a platform you can't build for locally, does not yet exist.
 
+## Authenticating
+
+You may need to log in to `https://isolateserver.appspot.com` to do this:
+
+```
+$ python tools/swarming_client/auth.py login \
+      --service=https://isolateserver.appspot.com
+```
+
+Use your google.com account for this.
+
 ## Uploading an isolate
 
 You can then upload the resulting isolate to the isolate server:
@@ -85,13 +170,6 @@ $ tools/swarming_client/isolate.py archive \
       -s $outdir/$target.isolated
 ```
 
-You may need to log in to `https://isolateserver.appspot.com` to do this:
-
-```
-$ python tools/swarming_client/auth.py login \
-      --service=https://isolateserver.appspot.com
-```
-
 The `isolate.py` tool will emit something like this:
 
 ```
@@ -153,33 +231,6 @@ The 'collect' command given there will block until the task is complete, then
 produce the task's results, or you can load that URL and watch the task's
 progress.
 
-## run-swarmed.py
-
-A lot of this logic is wrapped up in `tools/run-swarmed.py`, which you can run
-like this:
-
-```
-$ tools/run-swarmed.py $outdir $target
-```
-
-See the `--help` option of `run-swarmed.py` for more details about that script.
-
-## mb.py run
-
-Similar to `tools/run_swarmed.py`, `mb.py run` bundles much of the logic into a
-single command line. Unlike `tools/run_swarmed.py`, `mb.py run` allows the user
-to specify extra arguments to pass to the test, but has a messier command line.
-
-To use it, run:
-```
-$ tools/mb/mb.py run \
-    -s --no-default-dimensions \
-    -d pool $pool \
-    $criteria \
-    $outdir $target \
-    -- $extra_args
-```
-
 ## Other notes
 
 If you are looking at a Swarming task page, be sure to check the bottom of the