search

opensearch-project / documentation-website

The documentation for OpenSearch, OpenSearch Dashboards, and their associated plugins.
https://opensearch.org/docs
Apache License 2.0
64 stars 434 forks source link

[DOC] "Mappings" is overloaded #6443

Open smacrakis opened 4 months ago

smacrakis commented 4 months ago

What do you want to do?

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.

hdhalter commented 4 months ago

Thanks, Stavros, you make some good points. We can definitely take a look at how we are using the term mappings.

In the meantime, a great way to provide feedback is to use the 'edit this page' link in a page where you are confused, and enter your suggestion and push up a PR. We depend on product managers like you to provide input on context, so your viewpoint is critical. Creating a PR will help to expedite the change.

To your point >>shouldn't all technical terms be linked to their definitions throughout the documentation: we could do this if we published a glossary but we currently do not have one in the docs. It is on our list and we have an issue open for it, which I'll link here.

smacrakis commented 4 months ago

Thanks for your quick reply, Heather. I would propose edits except that in this case, I don't actually know anything about Security Analytics mappings. When I click on Edit this page, I get "You need to fork this repository to propose changes." I assume this is normal. To submit a PR, I click on "Commit changes...", right?

hdhalter commented 4 months ago

Thanks for your quick reply, Heather. I would propose edits except that in this case, I don't actually know anything about Security Analytics mappings. When I click on Edit this page, I get "You need to fork this repository to propose changes." I assume this is normal. To submit a PR, I click on "Commit changes...", right?

Yes, fork the repo, make the change, commit the change, then submit the PR. We'll take care of the rest unless we have questions or suggestions. Thanks, @smacrakis !