Clarify documentation on searchableAttributes

[bidoubiwa]

It is really not clear what searchableAttributes can do and how to use it in the documentation. It should be updated in the documentation in a way where it becomes clear for every user.

All information about searchable attributes

Fields to search in

Searchable attribute represents the lists of keys in which MeiliSearch will search when search queries are made. By default its value is "*". This symbol means that all keys are added automatically. They are added the following way:

• In the order they appeared in the first document added
• Every new key discovered in other documents are appended to the end of this list when they are discovered.

For example, if I add the following two documents

[
  {
    "title": "Batman",
    "id": 1
  },
   {
    "id": 2,
    "title": "Superman",
    "description": "a guy with a red underwear"
  }
]

In the first added document, the keys are ordered the following way, first title then id. This means that in searchableAttribute, this "*" symbol means this behind the scene: ["title", "id"]. When the second document is added, the description key is discovered and added to the end of the list. Searchable Attributes now looks like this: ["title", "id", "description"].

The fields order of importance

The order in which these keys are added is really important for the 4th ranking rule](https://docs.meilisearch.com/guides/main_concepts/relevancy.html#ranking-rules): Attribute.

4. Attribute
   Results are sorted according to the order of importance of the attributes: find documents that contain query terms in more important attributes first.

The order can not be known by the user unless he changes manually "*" with an array of keys ["title", "description"]

To change it manually, one must know what keys are present in the documents and then decide how to order them. Once they have chosen the right order, let's say ["title", "description"], the need to update the searchableAttribute settings using the update settings endpoint. From now on, new keys present in the newly added documents will not be automatically added to the searchable attribute list. They will have to be added manually.

Another important information is that when the searchableAttributes are reset, or if the whole settings are reset, the order that you have previously chosen will not be reset. This is not noticeable as the searchableAttribute as again this symbol "*".

Inspirations

A good way to handle this explanation is to take inspiration from Algolia since they have the same setting:
https://www.algolia.com/doc/guides/managing-results/must-do/searchable-attributes/.

as per requested here: meilisearch/specifications#3 (comment)

[dichotommy]

Fixed by #652