From 217d0c1fa5404055db6c944a46ca41e9ad918e79 Mon Sep 17 00:00:00 2001
From: Julie Tibshirani <julie.tibshirani@elastic.co>
Date: Fri, 13 Aug 2021 16:31:09 +0300
Subject: [PATCH] Mention match_only_text in disk usage docs (#76416)

* Mention match_only_text in disk usage docs

Previously we explained how to manually disable norms, freqs, and positions. We
now have a ready-made solution in the new `match_only_text` field type.

* Fixing typo and minor grammar changes

Co-authored-by: Adam Locke <adam.locke@elastic.co>
---
 docs/reference/how-to/disk-usage.asciidoc     | 73 +++----------------
 .../mapping/types/match-only-text.asciidoc    |  6 +-
 2 files changed, 12 insertions(+), 67 deletions(-)

diff --git a/docs/reference/how-to/disk-usage.asciidoc b/docs/reference/how-to/disk-usage.asciidoc
index efabcfc46a688..2552ac8bad7fc 100644
--- a/docs/reference/how-to/disk-usage.asciidoc
+++ b/docs/reference/how-to/disk-usage.asciidoc
@@ -4,14 +4,14 @@
 [discrete]
 === Disable the features you do not need
 
-By default Elasticsearch indexes and adds doc values to most fields so that they
-can be searched and aggregated out of the box. For instance if you have a numeric
+By default, {es} indexes and adds doc values to most fields so that they
+can be searched and aggregated out of the box. For instance, if you have a numeric
 field called `foo` that you need to run histograms on but that you never need to
 filter on, you can safely disable indexing on this field in your
 <<mappings,mappings>>:
 
 [source,console]
---------------------------------------------------
+----
 PUT index
 {
   "mappings": {
@@ -23,68 +23,13 @@ PUT index
     }
   }
 }
---------------------------------------------------
-
-<<text,`text`>> fields store normalization factors in the index in order to be
-able to score documents. If you only need matching capabilities on a `text`
-field but do not care about the produced scores, you can configure Elasticsearch
-to not write norms to the index:
-
-[source,console]
---------------------------------------------------
-PUT index
-{
-  "mappings": {
-    "properties": {
-      "foo": {
-        "type": "text",
-        "norms": false
-      }
-    }
-  }
-}
---------------------------------------------------
-
-<<text,`text`>> fields also store frequencies and positions in the index by
-default. Frequencies are used to compute scores and positions are used to run
-phrase queries. If you do not need to run phrase queries, you can tell
-Elasticsearch to not index positions:
+----
 
-[source,console]
---------------------------------------------------
-PUT index
-{
-  "mappings": {
-    "properties": {
-      "foo": {
-        "type": "text",
-        "index_options": "freqs"
-      }
-    }
-  }
-}
---------------------------------------------------
-
-Furthermore if you do not care about scoring either, you can configure
-Elasticsearch to just index matching documents for every term. You will
-still be able to search on this field, but phrase queries will raise errors
-and scoring will assume that terms appear only once in every document.
-
-[source,console]
---------------------------------------------------
-PUT index
-{
-  "mappings": {
-    "properties": {
-      "foo": {
-        "type": "text",
-        "norms": false,
-        "index_options": "freqs"
-      }
-    }
-  }
-}
---------------------------------------------------
+<<text,`text`>> fields store normalization factors in the index to facilitate
+document scoring. If you only need matching capabilities on a `text`
+field but do not care about the produced scores, you can use the
+<<match-only-text-field-type,`match_only_text`>> type instead. This field type
+saves significant space by dropping scoring and positional information.
 
 [discrete]
 [[default-dynamic-string-mapping]]
diff --git a/docs/reference/mapping/types/match-only-text.asciidoc b/docs/reference/mapping/types/match-only-text.asciidoc
index b3afa99ae54a4..0cb52586f41f0 100644
--- a/docs/reference/mapping/types/match-only-text.asciidoc
+++ b/docs/reference/mapping/types/match-only-text.asciidoc
@@ -20,10 +20,10 @@ Analysis is not configurable: text is always analyzed with the
 <<text-field-type,`text`>> field type if you absolutely need span queries.
 
 Other than that, `match_only_text` supports the same queries as `text`. And
-like `text`, it does not support sorting and has only limited support for aggretations.
+like `text`, it does not support sorting and has only limited support for aggregations.
 
 [source,console]
---------------------------------
+----
 PUT logs
 {
   "mappings": {
@@ -37,7 +37,7 @@ PUT logs
     }
   }
 }
---------------------------------
+----
 
 [discrete]
 [[match-only-text-params]]