[DOCS][101] Update first quick start with mappings examples

docs/reference/mapping.asciidoc

@@ -76,17 +76,23 @@ balance resource usage and performance. Your index will be smaller, but with
 slower search performance.
 
 [discrete]
-[[mapping-combine-explicit-dynamic]]
-== Combine explicit and dynamic mappings
+[[mapping-manage-update]]
+== Managing and updating mappings
 
-Explicit mappings should almost always be defined at index creation, because
-you can't change mappings for fields that already contain data.
+Explicit mappings should be defined at index creation for fields you know in advance. 
+You can still add _new fields_ to mappings at any time, as your data evolves.
 
-You can _update_ mappings for existing fields under certain conditions:
+Use the <<indices-put-mapping,Update mapping API>> to update an existing mapping.
 
-. You can add new fields to an existing mapping.
-. You can change the mapping for fields that don't contain any data.
-. You can add new <<multi-fields,multi-fields>> for existing fields.
+In most cases, you can't change mappings for fields that are already mapped.
+These changes require <<docs-reindex,reindexing>>.
+
+However, you can _update_ mappings under certain conditions:
+
+* You can add new fields to an existing mapping at any time, explicitly or dynamically.
+* You can add new <<multi-fields,multi-fields>> for existing fields.
+** Documents indexed before the mapping update will not have values for the new multi-fields until they are updated or reindexed. Documents indexed after the mapping change will automatically have values for the new multi-fields.
+* Some <<mapping-params,mapping parameters>> can be updated for existing fields of certain <<mapping-types,data types>>.
 
 [discrete]
 [[mapping-limit-settings]]

docs/reference/quickstart/getting-started.asciidoc

@@ -51,9 +51,9 @@ PUT /books
 ----
 // TEST[skip: index already setup]
 
-A `200` response indicates the index was created successfully.
+The following response indicates the index was created successfully.
 
-.Expand to see example response
+.Example response
 [%collapsible]
 ===============
 [source,console-result]
@@ -96,13 +96,18 @@ If the index didn't already exist, this request would automatically create it.
 [source,console]
 ----
 POST books/_doc
-{"name": "Snow Crash", "author": "Neal Stephenson", "release_date": "1992-06-01", "page_count": 470}
+{
+  "name": "Snow Crash",
+  "author": "Neal Stephenson",
+  "release_date": "1992-06-01",
+  "page_count": 470
+}
 ----
 // TEST[continued]
 
 The response includes metadata that {es} generates for the document, including a unique `_id` for the document within the index.
 
-.Expand to see example response with annotations
+.Example response
 [%collapsible]
 ===============
 [source,console-result]
@@ -159,7 +164,7 @@ POST /_bulk
 
 You should receive a response indicating there were no errors.
 
-.Expand to see example response
+.Example response
 [%collapsible]
 ===============
 [source,console-result]
@@ -267,7 +272,7 @@ You should receive a response indicating there were no errors.
 When using dynamic mapping, {es} automatically creates mappings for new fields by default.
 The documents we've added so far have used dynamic mapping, because we didn't specify a mapping when creating the index.
 
-Add a new document to the `books` index with a field that doesn't exist, to see how dynamic mapping works.
+To see how dynamic mapping works, add a new document to the `books` index with a field that doesn't exist.
 
 [source,console]
 ----
@@ -277,11 +282,12 @@ POST /books/_doc
   "author": "F. Scott Fitzgerald",
   "release_date": "1925-04-10",
   "page_count": 180,
-  "new_field": "I'm a new field added dynamically" <1>
+  "language": "EN" <1>
 }
 ----
 // TEST[continued]
-<1> This field is dynamically added to the document.
+<1> The new field.
+
 View the mapping for the `books` index. The new field `new_field` has been added to the mapping with a `text` data type.
 
 [source,console]
@@ -290,7 +296,7 @@ GET /books/_mapping
 ----
 // TEST[continued]
 
-.Expand to see example response
+.Example response
 [%collapsible]
 ===============
 [source,console-result]
@@ -344,7 +350,8 @@ GET /books/_mapping
 [[getting-started-explicit-mapping]]
 ==== Define explicit mapping
 
-Create an index named `my-explicit-mappings-books` with explicit mappings:
+Create an index named `my-explicit-mappings-books` with explicit mappings.
+Pass each field's properties as a JSON object. This object should contain the field type and any additional <<mapping-params,mapping parameters>>.
 
 [source,console]
 ----
@@ -353,22 +360,19 @@ PUT /my-explicit-mappings-books
   "mappings": {
     "dynamic": false,  <1>
     "properties": {  <2>
-      "name": { "type": "text" },  <3>
+      "name": { "type": "text" },
       "author": { "type": "text" },
-      "release_date": { "type": "date", "format": "yyyy-MM-dd" },  <4>
-      "page_count": { "type": "integer" }  <5>
+      "release_date": { "type": "date", "format": "yyyy-MM-dd" },
+      "page_count": { "type": "integer" }
     }
   }
 }
 ----
 // TEST[continued]
 <1> Disables dynamic mapping for the index. Documents containing fields not defined in the mapping will be rejected.
 <2> The `properties` object defines the fields and their data types for documents in this index.
-<3> Defines the "name" field as type "text", suitable for full-text search on book titles.
-<4> Specifies the "release_date" field as a "date" type with the specific format `yyyy-MM-dd`.
-<5> Sets the "page_count" field as an "integer" type for storing the number of pages.
 
-.Expand to see example response
+.Example response
 [%collapsible]
 ===============
 [source,console-result]
@@ -387,8 +391,11 @@ PUT /my-explicit-mappings-books
 ==== Combine dynamic and explicit mappings
 
 Explicit mappings are defined at index creation, and documents must conform to these mappings.
+You can also use the <<indices-put-mapping,Update mapping API>>.
 When an index has the `dynamic` flag set to `true`, you can add new fields to documents without updating the mapping.
-This allows you to <<mapping-combine-explicit-dynamic,combine explicit and dynamic mappings>>.
+
+This allows you to combine explicit and dynamic mappings.
+Learn more about <<mapping-manage-update,managing and updating mappings>>.
 
 [discrete]
 [[getting-started-search-data]]
@@ -409,7 +416,7 @@ GET books/_search
 ----
 // TEST[continued]
 
-.Expand to see (truncated) example response with annotations
+.Example response
 [%collapsible]
 ===============
 [source,console-result]
@@ -481,7 +488,7 @@ GET books/_search
 ----
 // TEST[continued]
 
-.Expand to see example response with annotations
+.Example response
 [%collapsible]
 ===============
 [source,console-result]
@@ -526,7 +533,7 @@ GET books/_search
 === Step 5: Delete your indices (optional)
 
 When following along with examples, you might want to delete an index to start from scratch.
-You can delete indices using the <<indices-delete-index,`DELETE` index API>>.
+You can delete indices using the <<indices-delete-index,Delete index API>>.
 
 For example, run the following command to delete the indices created in this tutorial:
 
@@ -541,5 +548,3 @@ DELETE /my-explicit-mappings-books
 ====
 Deleting an index permanently deletes its documents, shards, and metadata.
 ====
-
-