[memory-infra] Update docs on memory.top_10_mobile

docs/memory-infra/memory_benchmarks.md

 # Memory Benchmarks
 
 This document describes benchmarks available to track Chrome's and
 WebView's memory usage, where they live, what they measure, how to run them,
 and on how to diagnose regressions.
 
 [TOC]
 
 ## Glossary
 
@@ skipping 163 matching lines @@
 *   **kind:** The kind of memory being reported. For metrics reported by
     Chrome this usually is `effective_size` (others are `locked_size`
     and `allocated_objects_size`); for metrics by the OS this usually is
     `proportional_resident_size` (others are `peak_resident_size` and
     `private_dirty_size`).
 
 [memory-infra]: /memory-infra/README.md
 
 ## Appendix
 
-### Other benchmarks
+There are a few other benchmarks maintained by the memory-infra team.
+These also use the same set of metrics as system health, but have differences
+on the kind of stories that they run.
 
-Other benchmarks maintained by the memory-infra team are:
+### memory.top_10_mobile
+
+The *top-10-mobile* benchmarks are in the process of being deprecated
+in favor of system health benchmarks; but this process hasn't been finalized
+yet. Therefore, **it's still important to diagnose and fix regressions

[Primiano Tucci (use gerrit), 2017/01/17 12:15:48]

I'd add, after "finalized yet", "and currently they are the reference benchmark
used for the decision making process of the Android release"

[perezju, 2017/01/17 16:32:33]

Done.

+caught by these benchmarks**.
+
+*   [memory.top_10_mobile][memory_py] - Cycle between:
+
+    - load a page on Chrome, wait for it to load, force garbage collection,

[Primiano Tucci (use gerrit), 2017/01/17 12:15:48]

add also "simulate a memory pressure signal" (do I remember correctly?)

[perezju, 2017/01/17 16:32:33]

No. I added a link to the relevant piece of code. I think we did the "simulate a
memory pressure signal" experiment that one time when we thought it was relevant
to diagnose a particular regression; but the code didn't make it to the
checked-in benchmark.

+      measure memory;
+    - push Chrome to the background, force garbage collection, measure memory.
+
+    Repeat for each of 10 pages *without closing the browser*.
+
+    Close the browser, re-open and repeat the full page set a total of 5 times.
+
+    Story groups are either `foreground` or `background` depending on the state
+    of the browser at the time of measurement.
+
+*   [memory.top_10_mobile_stress][memory_py] - same as above, but keeps a single
+    instance of the browser open for the whole duration of the test and
+    *does not* force any garbage collection.
+
+One of the main differences between to watch out between these and system
+health benchmarks is that, since a single browser instance is kept open
+between individual *stories*, the `--story-filter` argument may affect the
+reproducibility of regressions. If you are having troubles reproducing a

[Primiano Tucci (use gerrit), 2017/01/17 12:15:48]

i'd just be stronger here and say: do not use --story filter when reproducing
this benchmark locally, as doing so affects the results

[perezju, 2017/01/17 16:32:33]

Done. Rephrased this bit.

+regression, try removing this option.
+
+### Dual browser benchmarks
+
+Dual browser benchmarks are intended to assess the memory implications of
+shared resources between Chrome and WebView.
 
 *   [memory.dual_browser_test][memory_py] - cycle between doing Google searches
     on a WebView-based browser (a stand-in for the Google Search app) and
     loading pages on Chrome. Runs on Android devices only.
 
     Story groups are either `on_chrome` or `on_webview`, indicating the browser
     in foreground at the moment when the memory measurement was made.
 
 *   [memory.long_running_dual_browser_test][memory_py] - same as above, but the
     test is run for 60 iterations keeping both browsers alive for the whole
     duration of the test and without forcing garbage collection. Intended as a
     last-resort net to catch memory leaks not apparent on shorter tests.
 
-*   [memory.top_10_mobile][memory_py] - cycle between loading a page on Chrome,
-    pushing the browser to the background, and then back to the foreground.
-    *(To be deprecated in favor of system_health.memory_mobile.)*
-
-    Story groups are either `foreground` or `background` indicating the state
-    of the browser at the time of measurement.
-
-*   [memory.top_10_mobile_stress][memory_py] - same as above, but keeps a single
-    instance of the browser open for 5 repetitions. *(To be deprecated.)*
-
 [memory_py]: https://chromium.googlesource.com/chromium/src/+/master/tools/perf/benchmarks/memory.py