[DOC] "Mappings" is overloaded

[smacrakis]

What do you want to do?

• [ X] Request a change to existing documentation
• [ ] Add new documentation
• [ ] Report a technical problem with the documentation
• [ ] Other

Tell us about your request. Provide a summary of the request and all versions that are affected.

I recently searched for [mapping] and got two pages at the top, one called Mappings APIs and the other called Mappings and field types. Naturally, I assumed that they were talking about the same thing.

But in fact, the word "mappings" is used in (at least) two radically different ways in OpenSearch. One has to do with the index schema (field types), the other has something to do with Security Analytics (though I don't understand what). Both the page Mappings APIs and the page Mappings and field types are returned by a search on [mappings]. This is very confusing since they apparently have nothing to do with each other. What's more, two different kinds of "mapping" are mentioned in the Security Analytics section: Field mappings and Roles mapping. I understand that mapping is a generic concept -- all the more reason to be clear in each case about what it is being applied to. And "field mappings" sounds the same as the other kind of ...um... field mapping.

It would be nice if (a) we gave them "full" names on first use in a page, e.g., "Security mappings" and "Field mappings" and (b) linked to the definition. The Mappings and field types page does give a definition in the first line, but the Mappings APIs page does not.

More generally, shouldn't all technical terms be linked to their definitions throughout the documentation? These days, we're all used to Wikipedia-style documents where you can start in the middle of a topic and follow links to improve your understanding.

Another protean term is "settings"....

What other resources are available? Provide links to related issues, POCs, steps for testing, etc.