elastic · elasticsearchmachine · Sep 10, 2024 · Sep 10, 2024
diff --git a/docs/reference/intro.asciidoc b/docs/reference/intro.asciidoc
@@ -14,12 +14,12 @@ Use {es} to search, index, store, and analyze data of all shapes and sizes in ne
 
 {es} is used for a wide and growing range of use cases. Here are a few examples:
 
-* *Monitor log and event data*. Store logs, metrics, and event data for observability and security information and event management (SIEM).
-* *Build search applications*. Add search capabilities to apps or websites, or build enterprise search engines over your organization's internal data sources.
-* *Vector database*. Store and search vectorized data, and create vector embeddings with built-in and third-party natural language processing (NLP) models.
-* *Retrieval augmented generation (RAG)*. Use {es} as a retrieval engine to augment Generative AI models.
-* *Application and security monitoring*. Monitor and analyze application performance and security data effectively.
-* *Machine learning*. Use {ml} to automatically model the behavior of your data in real-time.
+* *Monitor log and event data*: Store logs, metrics, and event data for observability and security information and event management (SIEM).
+* *Build search applications*: Add search capabilities to apps or websites, or build search engines over internal data.
+* *Vector database*: Store and search vectorized data, and create vector embeddings with built-in and third-party natural language processing (NLP) models.
+* *Retrieval augmented generation (RAG)*: Use {es} as a retrieval engine to augment generative AI models.
+* *Application and security monitoring*: Monitor and analyze application performance and security data.
+* *Machine learning*: Use {ml} to automatically model the behavior of your data in real-time.
 
 This is just a sample of search, observability, and security use cases enabled by {es}. 
 Refer to our https://www.elastic.co/customers/success-stories[customer success stories] for concrete examples across a range of industries.
@@ -41,25 +41,25 @@ https://www.elastic.co/guide/en/starting-with-the-elasticsearch-platform-and-its
 To use {es}, you need a running instance of the {es} service.
 You can deploy {es} in various ways:
 
-* <<run-elasticsearch-locally,*Local dev*>>. Get started quickly with a minimal local Docker setup. 
-* {cloud}/ec-getting-started-trial.html[*Elastic Cloud*]. {es} is available as part of our hosted Elastic Stack offering, deployed in the cloud with your provider of choice. Sign up for a https://cloud.elastic.co/registration[14 day free trial].
-* {serverless-docs}/general/sign-up-trial[*Elastic Cloud Serverless* (technical preview)]. Create serverless projects for autoscaled and fully managed {es} deployments. Sign up for a https://cloud.elastic.co/serverless-registration[14 day free trial].
+* <<run-elasticsearch-locally,*Local dev*>>: Get started quickly with a minimal local Docker setup. 
+* {cloud}/ec-getting-started-trial.html[*Elastic Cloud*]: {es} is available as part of our hosted Elastic Stack offering, deployed in the cloud with your provider of choice. Sign up for a https://cloud.elastic.co/registration[14-day free trial].
+* {serverless-docs}/general/sign-up-trial[*Elastic Cloud Serverless* (technical preview)]: Create serverless projects for autoscaled and fully managed {es} deployments. Sign up for a https://cloud.elastic.co/serverless-registration[14-day free trial].
 
 **Advanced deployment options**
 
-* <<elasticsearch-deployment-options,*Self-managed*>>. Install, configure, and run {es} on your own premises.
-* {ece-ref}/Elastic-Cloud-Enterprise-overview.html[*Elastic Cloud Enterprise*]. Deploy Elastic Cloud on public or private clouds, virtual machines, or your own premises.
-* {eck-ref}/k8s-overview.html[*Elastic Cloud on Kubernetes*]. Deploy Elastic Cloud on Kubernetes.
+* <<elasticsearch-deployment-options,*Self-managed*>>: Install, configure, and run {es} on your own premises.
+* {ece-ref}/Elastic-Cloud-Enterprise-overview.html[*Elastic Cloud Enterprise*]: Deploy Elastic Cloud on public or private clouds, virtual machines, or your own premises.
+* {eck-ref}/k8s-overview.html[*Elastic Cloud on Kubernetes*]: Deploy Elastic Cloud on Kubernetes.
 
 [discrete]
 [[elasticsearch-next-steps]]
 === Learn more
 
-Some resources to help you get started:
+Here are some resources to help you get started:
 
-* <<getting-started, Quickstart>>. A beginner's guide to deploying your first {es} instance, indexing data, and running queries.
-* https://elastic.co/webinars/getting-started-elasticsearch[Webinar: Introduction to {es}]. Register for our live webinars to learn directly from {es} experts.
-* https://www.elastic.co/search-labs[Elastic Search Labs]. Tutorials and blogs that explore AI-powered search using the latest {es} features.
+* <<getting-started, Quickstart>>: A beginner's guide to deploying your first {es} instance, indexing data, and running queries.
+* https://elastic.co/webinars/getting-started-elasticsearch[Webinar: Introduction to {es}]: Register for our live webinars to learn directly from {es} experts.
+* https://www.elastic.co/search-labs[Elastic Search Labs]: Tutorials and blogs that explore AI-powered search using the latest {es} features.
 ** Follow our tutorial https://www.elastic.co/search-labs/tutorials/search-tutorial/welcome[to build a hybrid search solution in Python].
 ** Check out the https://github.com/elastic/elasticsearch-labs?tab=readme-ov-file#elasticsearch-examples--apps[`elasticsearch-labs` repository] for a range of Python notebooks and apps for various use cases.
 
@@ -133,9 +133,9 @@ In {es}, metadata fields are prefixed with an underscore.
 
 The most important metadata fields are:
 
-* `_source`. Contains the original JSON document.
-* `_index`. The name of the index where the document is stored.
-* `_id`. The document's ID. IDs must be unique per index.
+* `_source`: Contains the original JSON document.
+* `_index`: The name of the index where the document is stored.
+* `_id`: The document's ID. IDs must be unique per index.
 
 [discrete]
 [[elasticsearch-intro-documents-fields-mappings]]
@@ -146,8 +146,8 @@ A mapping defines the <<mapping-types,data type>> for each field, how the field
 and how it should be stored.
 When adding documents to {es}, you have two options for mappings:
 
-* <<mapping-dynamic, Dynamic mapping>>. Let {es} automatically detect the data types and create the mappings for you. This is great for getting started quickly.
-* <<mapping-explicit, Explicit mapping>>. Define the mappings up front by specifying data types for each field. Recommended for production use cases.
+* <<mapping-dynamic, Dynamic mapping>>: Let {es} automatically detect the data types and create the mappings for you. This is great for getting started quickly, but can lead to unexpected results for complex data.
+* <<mapping-explicit, Explicit mapping>>: Define the mappings up front by specifying data types for each field. Recommended for production use cases, because you have much more control over how your data is indexed.
 
 [TIP]
 ====

diff --git a/docs/reference/mapping.asciidoc b/docs/reference/mapping.asciidoc
@@ -33,25 +33,42 @@ mapping values by overriding values in the mapping during the search request.
 [discrete]
 [[mapping-dynamic]]
 == Dynamic mapping
-<<dynamic-field-mapping,Dynamic mapping>> allows you to experiment with
-and explore data when you’re just getting started. {es} adds new fields
-automatically, just by indexing a document. You can add fields to the top-level
-mapping, and to inner <<object,`object`>>  and <<nested,`nested`>> fields.
+
+When you use <<dynamic-field-mapping,dynamic mapping>>, {es} automatically
+attempts to detect the data type of fields in your documents. This allows 
+you to get started quickly by just adding data to an index. If you index
+additional documents with new fields, {es} will add these fields automatically. 
+You can add fields to the top-level mapping, and to inner <<object,`object`>> 
+and <<nested,`nested`>> fields.
 
 Use <<dynamic-templates,dynamic templates>> to define custom mappings that are
 applied to dynamically added fields based on the matching condition.
 
 [discrete]
 [[mapping-explicit]]
 == Explicit mapping
-<<explicit-mapping,Explicit mapping>> allows you to precisely choose how to
-define the mapping definition, such as:
-
-* Which string fields should be treated as full text fields.
-* Which fields contain numbers, dates, or geolocations.
-* The <<mapping-date-format,format>> of date values.
-* Custom rules to control the mapping for
-  <<dynamic-mapping,dynamically added fields>>.
+
+Use <<explicit-mapping,explicit mapping>> to define exactly how data types
+are mapped to fields, customized to your specific use case.
+
+Defining your own mappings enables you to:
+
+* Define which string fields should be treated as full-text fields.
+* Define which fields contain numbers, dates, or geolocations.
+* Use data types that cannot be automatically detected (such as `geo_point` and `geo_shape`.)
+* Choose date value <<mapping-date-format,formats>>, including custom date formats.
+* Create custom rules to control the mapping for <<dynamic-mapping,dynamically added fields>>.
+* Optimize fields for partial matching.
+* Perform language-specific text analysis.
+
+[TIP]
+====
+It’s often useful to index the same field in different ways for different purposes.
+For example, you might want to index a string field as both a text field for full-text 
+search and as a keyword field for sorting or aggregating your data. Or, you might 
+choose to use more than one language analyzer to process the contents of a string field 
+that contains user input.
+====
 
 Use <<runtime-mapping-fields,runtime fields>> to make schema changes without
 reindexing. You can use runtime fields in conjunction with indexed fields to