Code sample naming standards and usage instructions

[guimachiavelli]

Code samples in our docs website are stored in /.code-samples.meilisearch.yaml. This file consists of a list of code snippets written by us for use in e.g. the CLI; each snippet is given a unique id which is then used by other teams to translate our curl examples into something usable by the various MeiliSearch's SDKs.

It is probably past time we establish some standards/conventions when deciding on code sample ids:

1. Minimise code sample re-use: in most cases we want a code sample to belong to a single page/text. For example: even if one code sample on the API reference and another in a cookbook are illustrating the same point (e.g. how to add documents to an index), they should be kept separate and assigned different ids;
2. Code sample ids should follow the pattern: `[feature/api][article][description]_[number]

• feature: this helps immediately identifying the feature we're trying to illustrate. We can skip this when articles are not illustrating a single feature. Examples:
  • displayed_attributes
  • api_keys
  • geosearch
• article: this helps homing where we can find the code sample being used. Examples: - guide - reference
• description: what is this code sample illustrating? Examples:
  • create_index
  • update_setting
  • delete_key
• number: certain use-cases might benefit from more than one example to illustrate different scenarios

Code sample id naming examples

- `displayed_attributes_reference_get_1`
- `api_keys_guide_create_key_1`
- `quick_start_create_index_2`

I'll keep updating the above list as our discussion begins to move along. Once we have defined a few rules, I'll make a task list so the issue becomes actionable.

Disclaimer for external contributors: we love you very much, but, since code samples require coordination between internal MeiliSearch teams, please refrain from requesting to work on this.

[dichotommy]

The typo tolerance guide code samples certainly need to have their names updated to meet this standard. See this comment for more information.

[maryamsulemani97]

All of the details have been moved to Notion. Closing this issue