Remove/simplify `learn/configuration/settings.md`

[guimachiavelli]

We currently have three separate spots where users can find information about a setting:

1. learn/configuration/settings.md
2. reference/api/settings.md
3. one article for each index setting under reference/api/

I believe this is bad because:

1. how can a user who searches for e.g. displayedAttributes which one of these pages is more likely to have the information they seek?
2. problem #1 is arguably mitigated if all three possible pages with info on a setting share the same content. But, if they share the same content, there is no point in having these three pages;
3. maintenance and updates become problematic: the same way a user needs to guess where the info they seek is, we need to guess where to place a certain piece of info.

From these pages, learn/configuration/settings.md seems like the least useful right now. At first glance the structure is out of sync with our recent updates and its actual aim is unclear (is it a reference? A guide? What will a user get from reading it?) but it's possible there's some unique content to it.

[dichotommy]

4. /learn/configuration also contains individual guides for Distinct attribute, displayed and searchable attributes, and synonyms.

[dichotommy]

I can't decide whether I agree or disagree with this. I guess I agree with a lot of what you're saying, so maybe it's just the way you phrased your conclusion that is bugging me.

First of all, the API reference (2 + 3 in your list): this is just accurate API documentation. Since Meilisearch provides the global settings route, plus individual routes for each setting, we are just accurately documenting the API, no?

You could make an argument that the individual settings routes are unnecessary when Meilisearch allows you to make partial updates using the global settings route (I would agree). But since these routes do exist, we have a responsibility to document them. So, 2 + 3 will not change until the API does.

What's left is the "learn" content related to settings: learn/configuration/settings.md + one guide each for distinct attribute, displayed + searchable attributes, and synonyms.

Here we can see some obvious problems. The quote-unquote overview (learn/configuration/settings.md) has a reference-like style and goes into extreme detail, containing some content that might be better suited to payload/request body definitions in the API reference. I support the idea of pruning this page and moving whatever information is related to requests and responses into the relevant API reference pages.

More importantly, though, it's simply not clear why certain settings have individual guides and not others, and whether a new user should read the individual guide for a setting first or read its description in the overview.

I think we agree that the learn section is meant for users who prefer guided content (more descriptive/less efficient) over reference content. So I think, either we provide a guided overview of index settings for those users—an article with a similar style to the individual settings guides. OR, we decide that we don't need a general "settings guide"—we really may not if we update the Indexes core concepts page accordingly—and instead focus on completing our individual settings guides. I am leaning towards this second approach.

In summary, I would suggest this process:

1. Review learn/configuration/settings.md. Move API-related content into the relevant API reference pages.
2. Use the remaining content as the basis to write the remaining ~5 individual settings guides.
3. Delete learn/configuration/settings.md

I think this matches the approach we have been taking so far: the API pages are tightly focused on the API (request body, response body, object definitions), while the guides offer more detailed explanation of behavior including edge cases. We just have to be careful that critical information is accessible for users doing troubleshooting, and not buried in too much prose.

So I guess in the end, I do agree? 😂

[guimachiavelli]

yeap, I think you do agree 😅

My point with this issue is reworking learn/configuration/settings.md—whether reworking means completely rewriting, removing, or something else is definitely up for discussion.

I do have a dislike for the sub-routes for settings in their current shape due to how it creates ambiguity in navigation and two information sources that look equally valid, but I think that's a separate discussion.

[maryamsulemani97]

With https://github.com/meilisearch/documentation/pull/1629, I think we can remove learn/configuration/settings.md. The Core concepts/Indexes page now has a summary of each index setting without any code samples