[DOCS] Update put mapping

[thekofimensah]

Added an intro to this topic to help with understanding of the topic

[github-actions]

Documentation preview:

• ✨ Changed pages

[elasticsearchmachine]

Pinging @elastic/es-docs (Team:Docs)

[leemthompo]

I would avoid manually editing API docs at this point because all API references are moving to being autogenerated from the OpenAPI specs. So my guidance would be to close this PR and focus on non-API docs updates.

Otherwise, I think these changes are problematic.

Your update has a few key issues that could mislead users:

• You've contradicted yourself by saying the API can "change mappings" but then stating Elasticsearch "does not allow in-place field type changes"
• You've removed the crucial "adds new fields" capability, which is actually one of the API's main functions

[lcawl]

I would avoid manually editing API docs at this point because all API references are moving to being autogenerated from the OpenAPI specs.

If updates to this content do need to go ahead, the appropriate file would be https://github.com/elastic/elasticsearch-specification/blob/main/specification/indices/put_mapping/IndicesPutMappingRequest.ts, which ultimately gets published here: https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-put-mapping-1

[leemthompo]

@thekofimensah need to address:

• You've contradicted yourself by saying the API can "change mappings" but then stating Elasticsearch "does not allow in-place field type changes"
• You've removed the crucial "adds new fields" capability, which is actually one of the API's main functions

[leemthompo]

Important

Elastic documentation is migrating to Markdown for version 9.0+. See the migration guide for details.

ℹ️ What's happening?

• Starting January 29, we will start closing all unmerged documentation PRs targeting main/master
• We're migrating from AsciiDoc to Markdown for 9.0+
• 9.0 docs will be frozen from January 29 until February 20 2024
• NOTE: PRs that include both code and documentation changes will remain open

What do I need to do?

For <=8.x docs:

1. Rebase your PR to target the relevant 8.x branch instead
2. The content can remain in AsciiDoc format

For 9.0+ docs:

Option 1:

• Draft docs in Markdown
• Once migration freeze ends, find the relevant page in the new docs system and use the edit options to submit your changes

Option 2:

• Open an issue in elastic/docs-content

💡 Need help?

1. For Elasticians: Ask in #docs Slack channel
2. For external contributors: Open an issue in elastic/docs-content

[thekofimensah]

@leemthompo For all of these tickets that we didn't quite get in before the finish line, shall I just create a new PR in v9 and drop these?

[leemthompo]

@thekofimensah yup, but remember some of these are API updates that need to happen in the spec, which is unaffected by the migration :)

[thekofimensah]

@leemthompo, @georgewallace for this one, it's targeting 8.17, so can this be merged as is?

[leemthompo]

Good to merge into 8.x.

Please follow up on #120248 (comment) if you want these changes reflected in 9.x API docs.

[elasticsearchmachine]

💚 Backport successful

Status	Branch	Result
✅	8.18
✅	8.x