Should examples used in the documentation work with the standard Movie dataset ?

[bidoubiwa]

Most of the examples found in the documentation work with the movie dataset available in the repository of meilisearch. This lets the user try out the examples as he reads the documentation.

Some examples does not work with the dataset because the dataset does not fit the use case.

The question is, should some example work with another datasat than the standart one. If yes, should the dataset be accessible where it is used so that the user can try it out ? Or at the contrary, should all the examples work with the standart movie dataset so that it is more easy for a user to try out the example ?

Example of a better usage than the movie dataset

For example the setting: distinct attributes. A good example to showcase its usage would a productId field in a product dataset.

Imagine the following dataset:

[
  { "id": 1, "name": "myBrand sneakers", "color": "red", "productId": "123" },
  { "id": 2, "name": "myBrand sneakers", "color": "blue", "productId": "123" },
  { "id": 3, "name": "myBrand sneakers", "color": "yellow", "productId": "123" },
  { "id": 4, "name": "anotherBrand sneakers", "color": "red", "productId": "456" }
]

With no specific setting, a search on sneaker will result in 4 hits, 3 times the same "myBrand" sneaker in different color and one time the "anotherBrand" sneaker. On most of e-commerces you would only see a specific sneaker once, and when clicking on it, discover the available colors.

Thus, by adding productId in the distinctAttribute, when searching for sneaker only two hits would appear.

This is a good example to explain distinctAttribute, which is not possible with the movie dataset.

[curquiza]

I'm not even sure that most users noticed the examples were written for the movies datasets, even if it's obvious there is a "movie" consistent throughout the docs. The dataset is only mentioned in the getting started if I'm not wrong, we do not declare anywhere "all our examples are made to fit this JSON dataset".

I think it's better to do understandable and accurate examples than being consistent with ONE dataset. Provide a dataset that is really relevant for all the situations is quite complicated.

For example, the "create an index" example does not show the real usage simplicity of MeiliSearch because MeiliSearch can infer the primary key in the example that is given. The dataset is not a concrete example of what is correct to do in this case. (2 examples might be great in this particular case since the primary key is a little bit tricky to understand)

[bidoubiwa]

So after discussion,

The only example the movie datasat should follow are the ones in the getting started guide.

As for the other examples they should be made as clear an concise as possible to be understood without the need of a functionning dataset.

Now because we thrive for simplicity of testing of the code samples, I will provide a small dataset for each example that is not compatible with the movie dataset.

Those examples may be used to tests the code samples.

Until this is merged, code-samples should not work with the movie dataset BUT should be compliant with the context in which it is showcased.

Example:

In add or replace documents.

Before the code samples the body is showcased. This mean that the code sample must follow that body.

[fharper]

If we decided to keep it that way, I would add a warning saying it's not a continuation of the guide, and that the examples are presented "as is" for the comprehension of the readers.

In the live last time, David wanted to try more things with our product, and it wasn't as straight forward because some examples weren't working with the movie dataset. I have done the same as David when I tested MeiliSearch for the first time, it's why I suggested to make them work with the right dataset or moving the examples to a dataset that used most, if not all the features we have.

Maybe it doesn't need to be like that if we plan to do a tutorial that goes to more "advanced" features after the getting started.

WDYT @react-learner ?