Tweak the style of histograms/README.md and improve clarity.

Clarity changes:
- Improved the wording in the Directly Measure What You Want and
  Expired histogram notifier sections
- Removed "will" since the present tense is preferred
- Replaced some unclear expressions with clearer ones

Style changes:
- Periods are now consistently followed by one (not two) spaces
- Hyphens are replaced with em dashes where appropriate and spacing
  around them is corrected (no spaces)


Change-Id: I94e845fcf64e761814f7ae448ab1a50015238698
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2500141
Commit-Queue: Caitlin Fischer <caitlinfischer@google.com>
Reviewed-by: Jesse Doherty <jwd@chromium.org>
Cr-Commit-Position: refs/heads/master@{#821316}

tools/metrics/histograms/README.md

@@ -64,16 +64,16 @@ macros; see [reasons above](#Coding-Emitting-to-Histograms).
 
 ### Directly Measure What You Want
 
-Measure exactly what you want, whether that's time used for a function call,
-number of bytes transmitted to fetch a page, number of items in a list, etc.
-Do not assume you can calculate what you want from other histograms.  Most of
-the ways to do this are incorrect.  For example, if you want to know the time
-taken by a function that all it does is call two other functions, both of which
-are have histogram logging, you might think you can simply add up those
-the histograms for those functions to get the total time.  This is wrong.
+Measure exactly what you want, whether that's the time used for a function call,
+the number of bytes transmitted to fetch a page, the number of items in a list,
+etc. Do not assume you can calculate what you want from other histograms. Most
+ways of doing this are incorrect. For example, suppose you want to know the time
+taken by a function that calls two other functions, both of which have histogram
+logging for their respective times. You might assume that you can simply sum the
+histograms for those two functions to get the total time, but this is incorrect.
 If we knew which emissions came from which calls, we could pair them up and
-derive the total time for the function.  However, histograms entries do not
-come with timestamps--we pair them up appropriately.  If you simply add up the
+derive the total time for the function. However, histogram entries do not come
+with timestamps to let us pair them up appropriately. If you simply add up the
 two histograms to get the total histogram, you're implicitly assuming those
 values are independent, which may not be the case. Directly measure what you
 care about; don't try to derive it from other data.
@@ -81,22 +81,22 @@ care about; don't try to derive it from other data.
 ### Enum Histograms
 
 Enumerated histogram are most appropriate when you have a list of connected /
-related states that should be analyzed jointly.  For example, the set of
-actions that can be done on the New Tab Page (use the omnibox, click a most
-visited tile, click a bookmark, etc.) would make a good enumerated histogram.
+related states that should be analyzed jointly. For example, the set of actions
+that can be done on the New Tab Page (use the omnibox, click a most visited
+tile, click a bookmark, etc.) would make a good enumerated histogram.
 If the total count of your histogram (i.e. the sum across all buckets) is
-something meaningful--as it is in this example--that is generally a good sign.
+something meaningful—as it is in this example—that is generally a good sign.
 However, the total count does not have to be meaningful for an enum histogram
 to still be the right choice.
 
 Enumerated histograms are also appropriate for counting events. Use a simple
-boolean histogram.  It's okay if you only log to one bucket (say, `true`).
-It's usually best (though not necessary), if you have a comparison point in
-the same histogram.  For example, if you want to count pages opened from the
-history page, it might be a useful comparison to have the same histogram
-record the number of times the history page was opened.
+boolean histogram. It's okay if you only log to one bucket (say, `true`). It's
+usually best, though not necessary, if you have a comparison point in the same
+histogram. For example, if you want to count pages opened from the history page,
+it might be a useful comparison to have the same histogram record the number of
+times the history page was opened.
 
-If only a few buckets will be emitted to, consider using a [sparse
+If only a few buckets are emitted to, consider using a [sparse
 histogram](#When-To-Use-Sparse-Histograms).
 
 #### Requirements
@@ -110,7 +110,7 @@ Enums logged in histograms must:
   ```
 - be numbered starting from `0`. Note this bullet point does *not* apply for
   enums logged with sparse histograms.
-- have enumerators with explicit values (`= 0`, `= 1`, `= 2`), to make it clear
+- have enumerators with explicit values (`= 0`, `= 1`, `= 2`) to make it clear
   that the actual values are important. This also makes it easy to match the
   values between the C++/Java definition and [histograms.xml](./histograms.xml).
 - not renumber or reuse enumerator values. When adding a new enumerator, append
@@ -118,8 +118,8 @@ Enums logged in histograms must:
   out, making it clear the value was previously used.
 
 If your enum histogram has a catch-all / miscellaneous bucket, put that bucket
-first (`= 0`). This will make the bucket easy to find on the dashboard if
-additional buckets are added later.
+first (`= 0`). This makes the bucket easy to find on the dashboard if additional
+buckets are added later.
 
 #### Usage
 
@@ -209,18 +209,18 @@ UmaHistogramEnumeration("NewTabPageAction", action, NewTabPageAction::kCount);
 
 When adding a new flag in
 [about_flags.cc](../../../chrome/browser/about_flags.cc), you need to add a
-corresponding entry to [enums.xml](./enums.xml). This will be automatically
-verified by the `AboutFlagsHistogramTest` unit test.
+corresponding entry to [enums.xml](./enums.xml). This is automatically verified
+by the `AboutFlagsHistogramTest` unit test.
 
 To add a new entry:
 
 1. Edit [enums.xml](./enums.xml), adding the feature to the `LoginCustomFlags`
    enum section, with any unique value (just make one up, although whatever it
-   is needs to appear in sorted order; `pretty_print.py` will do this for you).
+   is needs to appear in sorted order; `pretty_print.py` can do this for you).
 2. Build `unit_tests`, then run `unit_tests
    --gtest_filter='AboutFlagsHistogramTest.*'` to compute the correct value.
 3. Update the entry in [enums.xml](./enums.xml) with the correct value, and move
-   it so the list is sorted by value (`pretty_print.py` will do this for you).
+   it so the list is sorted by value (`pretty_print.py` can do this for you).
 4. Re-run the test to ensure the value and ordering are correct.
 
 You can also use `tools/metrics/histograms/validate_format.py` to check the
@@ -234,44 +234,43 @@ from previous Chrome versions.
 [histogram_macros.h](https://cs.chromium.org/chromium/src/base/metrics/histogram_macros.h)
 provides macros for some common count types such as memory or elapsed time, in
 addition to general count macros. These have reasonable default values; you
-will not often need to choose number of buckets or histogram min.  You still
-will need to choose the histogram max (use the advice below).
+seldom need to choose the number of buckets or histogram min. However, you still
+need to choose the histogram max (use the advice below).
 
 If none of the default macros work well for you, please thoughtfully choose
 a min, max, and bucket count for your histogram using the advice below.
 
 #### Count Histograms: Choosing Min and Max
 
-For histogram max, choose a value so that very few emission to the histogram
-will exceed the max.  If many emissions hit the max, it can be difficult to
-compute statistics such as average.  One rule of thumb is at most 1% of samples
+For histogram max, choose a value such that very few emissions to the histogram
+exceed the max. If many emissions hit the max, it can be difficult to compute
+statistics, such as the average. One rule of thumb is at most 1% of samples
 should be in the overflow bucket. This allows analysis of the 99th percentile.
 Err on the side of too large a range versus too short a range. (Remember that
 if you choose poorly, you'll have to wait for another release cycle to fix it.)
 
 For histogram min, if you care about all possible values (zero and above),
-choose a min of 1.  (All histograms have an underflow bucket; emitted zeros
-will go there.  That's why a min of 1 is appropriate.)  Otherwise, choose the
-min appropriate for your particular situation.
+choose a min of 1. (All histograms have an underflow bucket for emitted zeros,
+so a min of 1 is appropriate.) Otherwise, choose the min appropriate for your
+particular situation.
 
 #### Count Histograms: Choosing Number of Buckets
 
-Choose the smallest number of buckets that will get you the granularity you
-need.  By default count histograms bucket sizes scale exponentially so you can
-get fine granularity when the numbers are small yet still reasonable resolution
-for larger numbers.  The macros default to 50 buckets (or 100 buckets for
-histograms with wide ranges) which is appropriate for most purposes.  Because
-histograms pre-allocate all the buckets, the number of buckets selected
-directly dictate how much memory is used.  Do not exceed 100 buckets without
-good reason (and consider whether [sparse
-histograms](#When-To-Use-Sparse-Histograms) might work better for you in that
-case--they do not pre-allocate their buckets).
+Choose the smallest number of buckets that give you the granularity you need. By
+default, count histogram bucket sizes scale exponentially so you can get fine
+granularity when the numbers are small yet still reasonable resolution for
+larger numbers. The macros default to 50 buckets (or 100 buckets for histograms
+with wide ranges), which is appropriate for most purposes. Because histograms
+pre-allocate all the buckets, the number of buckets selected directly dictates
+how much memory is used. Do not exceed 100 buckets without good reason (and
+consider whether [sparse histograms](#When-To-Use-Sparse-Histograms) might work
+better for you in that case—they do not pre-allocate their buckets).
 
 ### Timing Histograms
 
 You can easily emit a time duration (time delta) using UMA_HISTOGRAM_TIMES,
-UMA_HISTOGRAM_MEDIUM_TIMES, and UMA_HISTOGRAM_LONG_TIMES macros, and their
-friends, as well as helpers such as SCOPED_UMA_HISTOGRAM_TIMER. Many timing
+UMA_HISTOGRAM_MEDIUM_TIMES, UMA_HISTOGRAM_LONG_TIMES macros, and their
+friends, as well as helpers like SCOPED_UMA_HISTOGRAM_TIMER. Many timing
 histograms are used for performance monitoring; if this is the case for you,
 please read [this document about how to structure timing histograms to make
 them more useful and
@@ -279,52 +278,50 @@ actionable](https://chromium.googlesource.com/chromium/src/+/lkgr/docs/speed/dia
 
 ### Percentage or Ratio Histograms
 
-You can easily emit a percentage histogram using the
-UMA_HISTOGRAM_PERCENTAGE macro provided in
+You can easily emit a percentage histogram using the UMA_HISTOGRAM_PERCENTAGE
+macro provided in
 [histogram_macros.h](https://cs.chromium.org/chromium/src/base/metrics/histogram_macros.h).
-You can also easily emit any ratio as a linear histogram (for equally
-sized buckets).
+You can also easily emit any ratio as a linear histogram (for equally sized
+buckets).
 
-For such histograms, you want each value recorded to cover approximately
-the same span of time.  This typically means emitting values periodically
-at a set time interval, such as every 5 minutes.  We do not recommend
-recording a ratio at the end of a video playback, as lengths of videos
-vary greatly.
+For such histograms, you want each value recorded to cover approximately the
+same span of time. This typically means emitting values periodically at a set
+time interval, such as every 5 minutes. We do not recommend recording a ratio at
+the end of a video playback, as video lengths vary greatly.
 
 It is okay to emit at the end of an animation sequence when what's being
-animated is fixed / known.  In this case, each value will represent
-roughly the same span of time.
+animated is fixed / known. In this case, each value represents roughly the same
+span of time.
 
-Why?  You typically cannot make decisions based on histograms whose
-values are recorded in response to an event that varies in length,
-because such metrics can conflate heavy usage with light usage.  It's
-easier to reason about metrics that route around this source of bias.
+Why? You typically cannot make decisions based on histograms whose values are
+recorded in response to an event that varies in length because such metrics can
+conflate heavy usage with light usage. It's easier to reason about metrics that
+avoid this source of bias.
 
 Many developers have been bitten by this. For example, it was previously common
-to emit an actions-per-minute ratio whenever Chrome was backgrounded.
-Precisely, these metrics computed the number of uses of a particular action
-during a Chrome session, divided by length of time Chrome had been open.
-Sometimes, the recorded rate was based on a short interaction with Chrome – a
-few seconds or a minute.  Other times, the recorded rate was based on a long
-interaction, tens of minutes or hours.  These two situations are
-indistinguishable in the UMA logs – the recorded values can be identical.
-
-This inability to distinguish these two qualitatively different settings make
+to emit an actions-per-minute ratio whenever Chrome was backgrounded. Precisely,
+these metrics computed the number of uses of a particular action during a Chrome
+session, divided by length of time Chrome had been open. Sometimes, the recorded
+rate was based on a short interaction with Chrome–a few seconds or a minute.
+Other times, the recorded rate was based on a long interaction, tens of minutes
+or hours. These two situations are  indistinguishable in the UMA logs–the
+recorded values can be identical.
+
+The inability to distinguish these two qualitatively different settings make
 such histograms effectively uninterpretable and not actionable. Emitting at a
-regular interval avoids the issue.  Each value will represent the same amount of
-time (e.g., one minute of video playback).
+regular interval avoids the issue. Each value represents the same amount of time
+(e.g., one minute of video playback).
 
 ### Local Histograms
 
 Histograms can be added via [Local macros](https://codesearch.chromium.org/chromium/src/base/metrics/histogram_macros_local.h).
-These will still record locally, but will not be uploaded to UMA and will
-therefore not be available for analysis. This can be useful for metrics only
-needed for local debugging. We don't recommend using local histograms outside
-of that scenario.
+These still record locally, but are not uploaded to UMA and are therefore not
+available for analysis. This can be useful for metrics only needed for local
+debugging. We don't recommend using local histograms outside of that scenario.
 
 ### Multidimensional Histograms
 
-It is common to be interested in logging multidimensional data - where multiple
+It is common to be interested in logging multidimensional data–where multiple
 pieces of information need to be logged together. For example, a developer may
 be interested in the counts of features X and Y based on whether a user is in
 state A or B. In this case, they want to know the count of X under state A,
@@ -334,47 +331,47 @@ There is no general purpose solution for this type of analysis. We suggest
 using the workaround of using an enum of length MxN, where you log each unique
 pair {state, feature} as a separate entry in the same enum. If this causes a
 large explosion in data (i.e. >100 enum entries), a [sparse histogram](#When-To-Use-Sparse-Histograms)
-may be appropriate. If you are unsure of the best way to proceed, please
-contact someone from the OWNERS file.
+may be appropriate. If you are unsure of the best way to proceed, please contact
+someone from the OWNERS file.
 
 ## Histogram Expiry
 
-Histogram expiry/expiration is specified by the `expires_after` attribute in
-histogram descriptions in histograms.xml. The attribute can be specified as date
-in **YYYY-MM-DD** format or as Chrome milestone in **M**\*(e.g. M68) format. In
-the latter case, the actual expiry date is about 12 weeks after that branch is
-cut, or basically when it is replaced on the "stable" channel by the following
+Histogram expiry is specified by the `expires_after` attribute in histogram
+descriptions in histograms.xml. The attribute can be specified as date in
+**YYYY-MM-DD** format or as Chrome milestone in **M**\*(e.g. M68) format. In the
+latter case, the actual expiry date is about 12 weeks after that branch is cut,
+or basically when it is replaced on the "stable" channel by the following
 release.
 
-After a histogram expires, it will cease to be displayed on the dashboard.
-However, the client may continue to send data for that histogram for some time
-after the official expiry date so simply bumping the 'expires_after' date in
-HEAD may be sufficient to resurrect it without any discontinuity. If too much
-time has passed and the client is no longer sending data, it can be re-enabled
-via Finch: see [Expired Histogram Whitelist](#Expired-histogram-whitelist).
+After a histogram expires, it ceases to be displayed on the dashboard. However,
+the client may continue to send data for that histogram for some time after the
+official expiry date so simply bumping the 'expires_after' date at HEAD may be
+sufficient to resurrect it without any discontinuity. If too much time has
+passed and the client is no longer sending data, it can be re-enabled via Finch:
+see [Expired Histogram Whitelist](#Expired-histogram-whitelist).
 
-Once a histogram has expired, the code to record it becomes dead code and should
-be removed from the codebase along with marking the histogram definition as
-obsolete.
+Once a histogram has expired, the code that records it becomes dead code and
+should be removed from the codebase along with marking the histogram definition
+as obsolete.
 
 In **rare** cases, the expiry can be set to "never". This is used to denote
 metrics of critical importance that are, typically, used for other reports.
 For example, all metrics of the "[heartbeat](https://uma.googleplex.com/p/chrome/variations)"
-are set to never expire.  All metrics that never expire must have an XML
-comment describing why so that it can be audited in the future.
+are set to never expire. All metrics that never expire must have an XML comment
+describing why so that it can be audited in the future.
 
 ```
 <!-- expires-never: "heartbeat" metric (internal: go/uma-heartbeats) -->
 ```
 
-For all the new histograms the use of expiry attribute will be strongly
-encouraged and enforced by Chrome metrics team through reviews.
+For all new histograms, the use of expiry attribute is strongly encouraged and
+enforced by the Chrome Metrics team through reviews.
 
 #### How to choose expiry for histograms
 
-If you are adding a histogram that will be used to evaluate a feature launch,
-set an expiry date consistent with the expected feature launch date. Otherwise,
-we recommend choosing 3-6 months.
+If you are adding a histogram to evaluate a feature launch, set an expiry date
+consistent with the expected feature launch date. Otherwise, we recommend
+choosing 3-6 months.
 
 Here are some guidelines for common scenarios:
 
@@ -384,8 +381,8 @@ Here are some guidelines for common scenarios:
     remove it.
 *   If the histogram is not in use now, but might be useful in the near
     future, pick ~3 months or ~2 milestones ahead.
-*   If the histogram is actively in use now and useful for a short term, pick
-    3-6 month or 2-4 milestones ahead.
+*   If the histogram is actively in use now and is useful in the short term,
+    pick 3-6 months or 2-4 milestones ahead.
 *   If the histogram is actively in use and seems useful for an indefinite time,
     pick 1 year.
 
@@ -396,18 +393,20 @@ doc](https://docs.google.com/document/d/1IEAeBF9UnYQMDfyh2gdvE7WlUKsfIXIZUw7qNoU
 
 ### Expired histogram notifier
 
-Expired histogram notifier will notify owners in advance by creating crbugs so
-that the owners can extend the lifetime of the histogram if needed or deprecate
-it. It will regularly check all the histograms in histograms.xml and will
-determine expired histograms or histograms expiring soon. Based on that it will
-create or update crbugs that will be assigned to histogram owners.
+The expired histogram notifier notifies histogram owners before their histograms
+expire by creating crbugs, which are assigned to owners. This allows owners to
+extend the lifetime of their histograms, if needed, or deprecate them. The
+notifier regularly checks all histograms across the histograms.xml files and
+identifies expired or soon-to-be expired histograms. It then creates or updates
+crbugs accordingly.
 
 ### Expired histogram whitelist
 
-If a histogram expires but turns out to be useful, you can add histogram name
-to the whitelist until the updated expiration date reaches to the stable
-channel. For adding histogram to the whitelist, see internal documentation
-[Histogram Expiry](https://goto.google.com/histogram-expiry-gdoc)
+If a histogram expires but turns out to be useful, you can add the histogram's
+name to the whitelist until the updated expiration date reaches the stable
+channel. For adding a histogram to the whitelist, see the internal
+documentation:
+[Histogram Expiry](https://goto.google.com/histogram-expiry-gdoc).
 
 ## Testing
 
@@ -417,8 +416,8 @@ the values emitted to are correct.  Finally, for count histograms, make sure
 that buckets capture enough precision for your needs over the range.
 
 Pro tip: You can filter the set of histograms shown on `chrome://histograms` by
-specifying a prefix. For example, `chrome://histograms/Extensions.Load` will
-show only histograms whose names match the pattern "Extensions.Load*".
+specifying a prefix. For example, `chrome://histograms/Extensions.Load` shows
+only histograms whose names match the pattern "Extensions.Load*".
 
 In addition to testing interactively, you can have unit tests examine the
 values emitted to histograms. See [histogram_tester.h](https://cs.chromium.org/chromium/src/base/test/metrics/histogram_tester.h)
@@ -439,12 +438,12 @@ not entirely so.
 
 When changing the semantics of a histogram (when it's emitted, what buckets
 mean, etc.), make it into a new histogram with a new name. Otherwise the
-"Everything" view on the dashboard will be mixing two different
-interpretations of the data and make no sense.
+"Everything" view on the dashboard will mix two different interpretations of the
+data and make no sense.
 
 ## Deleting Histograms
 
-Please delete the code that emits to histograms that are no longer needed.
+Please delete code that emits to histograms that are no longer needed.
 Histograms take up memory. Cleaning up histograms that you no longer care
 about is good! But see the note below on
 [Cleaning Up Histogram Entries](#Cleaning-Up-Histogram-Entries).
@@ -453,7 +452,7 @@ about is good!  But see the note below on
 
 Document histograms in [histograms.xml](./histograms.xml). There is also a
 [google-internal version of the file](http://go/chrome-histograms-internal) for
-the rare case when the histogram is confidential (added only to Chrome code,
+the rare case in which the histogram is confidential (added only to Chrome code,
 not Chromium code; or, an accurate description about how to interpret the
 histogram would reveal information about Google's plans).
 
@@ -466,7 +465,7 @@ several benefits.  One, it sometimes happens that the
 histogram description that reveal problems with interpretation of the data and
 call for a different recording strategy. Two, it allows the histogram reviewer
 to easily review the emission code to see if it comports with these best
-practices, and to look for other errors.
+practices and to look for other errors.
 
 ### Understandable to Everyone
 
@@ -501,20 +500,21 @@ contact for any questions or maintenance tasks, such as extending a histogram's
 expiry or deprecating the metric.
 
 Histograms must have a primary owner and may have secondary owners. A primary
-owner is an individual, e.g. <owner>lucy@chromium.org</owner>, who is
-ultimately responsible for maintaining the metric. Secondary owners may be
-other individuals, team mailing lists, e.g. <owner>my-team@google.com</owner>,
-or paths to OWNERS files, e.g. <owner>src/directory/OWNERS</owner>.
+owner is an individual with an @chromium.org or @google.com email address, e.g.
+<owner>lucy@chromium.org</owner>, who is ultimately responsible for maintaining
+the metric. Secondary owners may be other individuals, team mailing lists, e.g.
+<owner>my-team@google.com</owner>, or paths to OWNERS files, e.g.
+<owner>src/directory/OWNERS</owner>.
 
 It's a best practice to list multiple owners, so that there's no single point
 of failure for histogram-related questions and maintenance tasks. If you are
 using a metric heavily and understand it intimately, feel free to add yourself
-as an owner. For individuals, @chromium.org email addresses are preferred.
+as an owner.
 
 Notably, owners are asked to determine whether histograms have outlived their
-usefulness. When a histogram is nearing expiry, a robot will file a reminder
-bug in Monorail. It's important that somebody familiar with the histogram
-notices and triages such bugs!
+usefulness. When a histogram is nearing expiry, a robot files a reminder bug in
+Monorail. It's important that somebody familiar with the histogram notices and
+triages such bugs!
 
 ### Components
 
@@ -531,9 +531,9 @@ does, then the parent directory's component is used.
 
 ### Cleaning Up Histogram Entries
 
-Do not delete histograms from histograms.xml. Instead, mark unused
-histograms as obsolete and annotate them with the date or milestone in
-the `<obsolete>` tag entry.
+Do not delete histograms from histograms.xml. Instead, mark unused histograms as
+obsolete and annotate them with the date or milestone in the `<obsolete>` tag
+entry.
 
 If deprecating only some variants of a
 [patterned histogram](#Patterned-Histograms), mark each deprecated `<variant>`
@@ -544,12 +544,12 @@ If the histogram is being replaced by a new version:
 
 * Note in the `<obsolete>` message the name of the replacement histogram.
 
-* Make sure the descriptions of the original and replacement histogram
-  are different.  It's never appropriate for them to be identical.  Either
-  the old description was wrong, and it should be revised to explain what
-  it actually measured, or the old histogram was measuring something not
-  as useful as the replacement, in which case the new histogram is
-  measuring something different and needs to have a new description.
+* Make sure the descriptions of the original and replacement histogram are
+  different. It's never appropriate for them to be identical. Either the old
+  description was wrong, and it should be revised to explain what it actually
+  measured, or the old histogram was measuring something not as useful as the
+  replacement, in which case the new histogram is measuring something different
+  and needs to have a new description.
 
 A changelist that marks a histogram as obsolete should be reviewed by all
 current owners.
@@ -557,7 +557,7 @@ current owners.
 Deleting histogram entries would be bad if someone to accidentally reused your
 old histogram name and thereby corrupts new data with whatever old data is still
 coming in. It's also useful to keep obsolete histogram descriptions in
-[histograms.xml](./histograms.xml) -- that way, if someone is searching for a
+[histograms.xml](./histograms.xml)—that way, if someone is searching for a
 histogram to answer a particular question, they can learn if there was a
 histogram at some point that did so even if it isn't active now.
 
@@ -607,8 +607,8 @@ This example defines metadata for 12 (= 3 x 4) concrete histograms, such as
 
 Note that each token `<variant>` defines what text should be substituted for it,
 both in the histogram name and in the summary text. As shorthand, a `<variant>`
-that omits the `summary` attribute will substitute the value of the `name`
-attribute in the histogram's `<summary>` text as well.
+that omits the `summary` attribute substitutes the value of the `name` attribute
+in the histogram's `<summary>` text as well.
 
 *** promo
 Tip: You can declare an optional token by listing an empty name: `<variant
@@ -622,7 +622,7 @@ of histograms. See
 [histograms.xml](https://source.chromium.org/search?q=file:histograms.xml%20%3Cvariants)
 for examples.
 
-By default, a `<variant>` will inherit the owners declared for the patterned
+By default, a `<variant>` inherits the owners declared for the patterned
 histogram. Each variant can optionally override the inherited list with custom
 owners:
 ```xml
@@ -650,7 +650,7 @@ https://chromium.googlesource.com/chromium/src/+/refs/tags/87.0.4270.1/tools/met
 
 ## When To Use Sparse Histograms
 
-Sparse histograms are well suited for recording counts of exact sample values
+Sparse histograms are well-suited for recording counts of exact sample values
 that are sparsely distributed over a large range. They can be used with enums
 as well as regular integer values. It is often valuable to provide labels in
 [enums.xml](./enums.xml).