[DOCS] Upsert documentation clarification

[lcawl]

This PR copies over updates made in elastic/elasticsearch#120684

[github-actions]

Following you can find the validation results for the APIs you have changed.

API	Status	Request	Response
update	🟢	35/35	35/35

You can validate these APIs yourself by using the make validate target.

[leemthompo]

You're too fast @lcawl! Might be a few tweaks on original but perhaps @thekofimensah could handle the updates? We mentioned previously that API docs updates need to prioritize working in the spec, rather than the old asciidoc docs.

[kilfoyle]

LGTM! 🐫

[lcawl]

You're too fast @lcawl! Might be a few tweaks on original but perhaps @thekofimensah could handle the updates? We mentioned previously that API docs updates need to prioritize working in the spec, rather than the old asciidoc docs.

Sure! @thekofimensah if you want to contribute to this PR or replace it with another, lmk! Or if you want to chat about any of the processes related to this repo, I'm happy to chat too