Examples section in README

[curquiza]

Currently, all the SDKs have an Examples section.

Maybe I'm in the future because it's not done yet for all the SDK but anyway 😬... once an SDK has completed all the examples for the main docs (I mean docs.meilisearch.com) including examples in guides (like the JS does), not only in the API references, I think we should remove the Example section and redirect the user to the API references.

What do you think?

(I don't forget that some custom methods for SDKs like wait_for_pending_update are not going to be documented in the main docs, but the current Example section is not related to them and I suggest we discuss that in another discussion 😉)

If you agree with this removal, how could we redirect clearly to the API references?

[eskombro]

I am not sure about that. Docs examples are a must have, but they are examples of every single functionality / route, their nature is not the same. They are short, simple, straightforward. But they don't have the same value as an example of a 'hello world' working project creating a client, an index, adding documents, etc. The readme examples show you the 'workflow' for which you need way more time and mental effort to get from the docs directly. It is great to have a copy/paste working example that let you play directly with a new product/project without needing to read the docs and understand the main concepts. When you have this, you try it, you see it works, then you get curious and read the docs. Well, that's my point of view, but I don't really understand why you want to remove it. I mean, you are proposing it but I don't see clearly what the argument is.

About the custom methods, I was actually thinking about it yesterday and I'll make a different discussion as you suggest

[curquiza]

Sorry, I wasn't clear because it was obvious to me, but it's not, my bad 😅

When you write a README you have 2 possibilities:

• write the docs on the README
• redirect to the official docs

We didn't have any docs for the SDKs, that's why we use the Examples section.

But most of the famous packages do not use README for docs, they redirect the user to the official one in the first paragraphs:

• Algolia: https://github.com/algolia/algoliasearch-client-ruby
• Stripe (all the examples you can find in the README are specific to the SDKs and do not correspond to the API methods you can find in their docs): https://github.com/stripe/stripe-ruby

I took both of them because they offer good documentation experience, but you can find the same behavior for other packages, like Sidekiq or Scrapy... When the package is becoming bigger and bigger, the solution is often to give up the README documentation and focus on an official and clearer one.

Plus:

• my suggestion avoids duplication of documentation
• the Examples section is not even complete: there is no example about settings and too few about searching. So, if we choose to keep this section, we definitely need to complete it.

For me, redirect the user to the official docs could be a good practice. It's not mandatory (not everyone in the OS community adopts this solution) but it's a possibility we should consider, especially because we are not stable and maintain double documentation could be a pain.
That's why I suggest that 😉

What do you think @tpayet and @bidoubiwa?

NB: of course, I've never mentioned removing the Getting Started section.

[eskombro]

After reading your explanation I totally agree with you. My bad, I did think you were also thinking about getting rid of the getting started section. If that section stays on the readme, I don't think we need to keep / maintenant the examples section, and we can delete it, indeed 👍

[curquiza]

That's my fault, I should have written that at first 😅 I posted it too fast! 😇

[curquiza]

@bidoubiwa @eskombro : I didn't get any answer about

If you agree with this removal, how could we redirect clearly to the API references?

(that my fault, I put the ready to implement label, but it's not)

It could be simple, but I want your opinion on:

• what kind of sentence
• where in the README
• ...

[eskombro]

I think we should replace the Examples section (in place) with a short invitation to read the docs as follows (my first proposition to start with):

---

🎬 Documentation and examples

MeiliSearch documentation provides examples and a detailed explanation of every one of it's features and functionalities, including examples on how to implement them using this SDK.

Please read our Documentation guides or check the API References to find the one that you need!