Improve the field type documentation.

Author: jtibshirani

docs/reference/mapping/types/embedded-json.asciidoc

@@ -5,30 +5,27 @@ By default, each subfield in an object is mapped and indexed separately. If
 the names or types of the subfields are not known in advance, then they are
 <<dynamic-mapping, mapped dynamically>>.
 
-The `embedded_json` type provides an alternative approach, where the entire object is
-mapped as a single field. Given an object, the `embedded_json` mapping will parse out
-its leaf values and index them into one field. The object's contents can then
-be searched through simple keyword-style queries.
-
-This data type can be useful for indexing objects with a very large number of
-distinct keys. Compared to mapping each field separately, embedded JSON fields have
-the following advantages:
-
-- Only one field mapping is created for the whole object, which can help
-  prevent a <<mapping-limit-settings, mappings explosion>> due to a large
-  number of field mappings.
-- An embedded JSON field may take up less space in the index, as only one underlying
-  field is created.
-
-However, embedded JSON fields present a trade-off in terms of search functionality.
-Only basic queries are allowed, with no support for numeric range queries or
-highlighting. Further information on the limitations can be found in the
-<<supported-operations, Supported operations>> section.
-
-NOTE: The `embedded_json` mapping type should **not** be used for indexing all JSON
-content, as it provides only limited search functionality. The default
-approach, where each subfield has its own entry in the mappings, works well in
-the majority of cases.
+The `embedded_json` type provides an alternative approach, where the entire
+object is mapped as a single field. Given an object, the `embedded_json`
+mapping will parse out its leaf values and index them into one field as
+keywords. The object's contents can then be searched through simple queries
+and aggregations.
+
+This data type can be useful for indexing objects with a large or unknown
+number of unique keys. Embedded JSON fields create only one field mapping
+for the whole object, which can help prevent a
+<<mapping-limit-settings, mappings explosion>> from having too many distinct
+field mappings.
+
+However, embedded JSON fields present a trade-off in terms of search
+functionality. Only basic queries are allowed, with no support for numeric
+range queries or highlighting. Further information on the limitations can be
+found in the <<supported-operations, Supported operations>> section.
+
+NOTE: The `embedded_json` mapping type should **not** be used for indexing all
+JSON content, as it treats all values as keywords and does not provide full
+search functionality. The default approach, where each subfield has its own
+entry in the mappings, works well in the majority of cases.
 
 An embedded JSON field can be created as follows:
 [source,js]
@@ -67,7 +64,9 @@ During indexing, tokens are created for each leaf value in the JSON object. The
 values are indexed as string keywords, without analysis or special handling for
 numbers or dates.
 
-Querying the top-level `embedded_json` field searches all leaf values in the object:
+Querying the top-level `embedded_json` field searches all leaf values in the
+object:
+
 [source,js]
 --------------------------------
 POST bug_reports/_search
@@ -94,6 +93,10 @@ POST bug_reports/_search
 [[supported-operations]]
 ==== Supported operations
 
+Because of the similarities in the way values are indexed, `embedded_json`
+fields share much of the same mapping and search functionality as
+<<keyword, `keyword`>> fields.
+
 Currently, embedded JSON fields can be used with the following query types:
 
 - `term`, `terms`, and `terms_set`
@@ -119,9 +122,7 @@ the <<mapping-store, `store`>> parameter in the mapping.
 [[json-params]]
 ==== Parameters for JSON fields
 
-Because of the similarities in the way values are indexed, the `embedded_json` type
-shares many mapping options with <<keyword, `keyword`>>. The following
-parameters are accepted:
+The following mapping parameters are accepted:
 
 [horizontal]