Refactor Histogram relationship diagnostics.

docs/how-to-write-metrics.md

 <!-- Copyright 2016 The Chromium Authors. All rights reserved.
      Use of this source code is governed by a BSD-style license that can be
      found in the LICENSE file.
 -->
 
 # How to Write Metrics
 
 Timeline-Based Measurement v2 is a system for computing metrics from traces.
 
 A TBM2 metric is a Javascript function that takes a trace Model and produces
@@ skipping 129 matching lines @@
 
    ![](/docs/images/how-to-write-metrics-related-event-set.png)
 
  * [DateRange](/tracing/tracing/value/diagnostics/date_range.html):
    This is a Range of Dates. It cannot be empty, but the minDate could be the
    same as the maxDate. Telemetry automatically adds 2 shared DateRanges to all
    results: 'benchmarkStart' and 'traceStart'.
 
    ![](/docs/images/how-to-write-metrics-date-range.png)
 
-### Histogram Relationship Diagnostics
 
- * [RelatedHistogramMap](/tracing/tracing/value/diagnostics/related_histogram_map.html):
-   These are Maps from strings to references to other Histograms. Visually, they
-   are a set of HTML links where the text content of the link is the Map's
-   string key instead of the Histogram's name. One example application is when a
-   Histogram was produced not directly by a metric, but rather by merging
-   together other Histograms, then it will have a RelatedHistogramMap named
-   'mergedFrom' that refers to the Histograms that were merged by their grouping
-   key, e.g. the telemetry story name.
+### Related Histogram Name Map
 
-   ![](/docs/images/how-to-write-metrics-related-histogram-map.png)
-
- * [RelatedHistogramBreakdown](/tracing/tracing/value/diagnostics/related_histogram_breakdown.html):
-   Structurally, this is a RelatedHistogramMap, but conceptually and visually, this
-   is a Breakdown. Whereas Breakdown's stacked bar chart derives its data from
-   the numbers contained explicitly in the Breakdown, a
-   RelatedHistogramBreakdown's stacked
-   bar chart derives its data from the referenced Histograms' sums.
-
-   ![](/docs/images/how-to-write-metrics-related-histogram-breakdown.png)
+ * [RelatedNameMap](/tracing/tracing/value/diagnostics/related_name_map.html):
+   This maps from short keys to Histogram name. These are correlated with
+   Breakdowns. They are visualized as HTML links.
 
 
 ### Other Diagnostics
 
  * [Scalar](/tracing/tracing/value/diagnostics/scalar.html):
    Metrics must not use this, since it is incapable of being merged. It is
    mentioned here for completeness. It wraps a Scalar, which is just a
    unitted number. This is only to allow Histograms in other parts of the trace
    viewer to display number sample diagnostics more intelligently than
    GenericSet can. If a metric wants to display number sample diagnostics
-   intelligently, then it should use RelatedHistogramMap; if it does not want to
+   intelligently, then it should use Breakdown; if it does not want to
    monitor changes in those numbers, then the TBM2 maintainers can add a
    HistogramDiagnostic that supports merging.
 
 
 ### Reserved Names
 
 Metrics may not use the following names for Histogram-level Diagnostics.
 
  * angleRevisions is a GenericSet of strings containing
    [Angle](https://chromium.googlesource.com/angle/angle/) git hashes.
@@ skipping 102 matching lines @@
   * Instead of having one category for all story grouping keys, each grouping
     individual grouping key may be listed as a category. For example, in Page
     Cycler v2 benchmarks, the "cache_temperature" grouping key would be
     displayed as a category.
 * Choosing groups builds a hierarchy of histograms that is filled in by merging
   histograms from the bottom up. Expanding the rows of histogram-set-table, any
   leaf nodes are histograms that were loaded, and their ancestors are computed by
   merging.
 * histogram-set-table uses the "label" HistogramGrouping to define the columns
   of the table.