[memory-infra] Update docs on memory.top_10_mobile

docs/memory-infra/memory_benchmarks.md

Index: docs/memory-infra/memory_benchmarks.md
diff --git a/docs/memory-infra/memory_benchmarks.md b/docs/memory-infra/memory_benchmarks.md
index c33610afe10a920df632efb74c019efe8cbe4d87..853eb583e645813adaf624ae5897ba8daf126388 100644
--- a/docs/memory-infra/memory_benchmarks.md
+++ b/docs/memory-infra/memory_benchmarks.md
@@ -181,9 +181,44 @@ where:
 
 ## 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
@@ -197,14 +232,4 @@ Other benchmarks maintained by the memory-infra team are:
     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