first drafts ready

config/sidebar-learn.json

@@ -258,9 +258,9 @@
     "slug": "multi_search",
     "routes": [
       {
-        "source": "learn/multi_search/federated_search_guide.mdx",
-        "label": "Federated search guide",
-        "slug": "federated_search_guide"
+        "source": "learn/multi_search/performing_federated_search.mdx",
+        "label": "Using multi-search to perform a federated search",
+        "slug": "performing_federated_search"
       },
       {
         "source": "learn/multi_search/multi_search_vs_federated_search.mdx",

learn/multi_search/multi_search_vs_federated_search.mdx

@@ -1,26 +1,26 @@
 ---
 title: Differences between multi-search and federated search — Meilisearch API reference
-description: 
+description: This article defines multi-search and federated search and then describes the different uses of each.
 ---
 
 # Differences between multi-search and federated search
 
-This article describes the different uses of federated search and multi-search.
+This article defines multi-search and federated search and then describes the different uses of each.
 
 ## What is multi-search?
 
-Multi-search, also called multi-index search, is a search operation that queries two or more indexes at the same time. Meilisearch returns a separated list results for each index. Use the `/multi-search` route to perform multi-searches.
+Multi-search, also called multi-index search, is a search operation that queries two or more indexes at the same time. Meilisearch then returns a separate list results for each index. Use the `/multi-search` route to perform multi-searches.
 
-Multi-search favors discovery scenarios, where searches might have several valid results.
+Multi-search favors discovery scenarios, where users might not have a clear idea of what they need and searches might have many valid results.
 
 ## What is federated search?
 
-Federated search is a type of multi-index search. This operation also queries multiple indexes, but returns a single list with the most relevant results across all queried indexes. Use the `/multi-search` route and specify a non-null value for `federation` to perform a federated search.
+Federated search is a type of multi-index search. This operation also queries multiple indexes, but returns a single list with the most relevant results from all queried indexes. Use the `/multi-search` route and specify a non-null value for `federation` to perform a federated search.
 
 Federated search favors scenarios where users have a clear idea of what they need and expect a single best top result.
 
 ## Use cases
 
-Because multi-search groups results by index, it is often useful when a document's index contains information relevant to your users. For example, a person searching for `shygirl` in a music streaming application is likely to appreciate seeing separate results for matching artists, albums, and individual tracks.
+Because multi-search groups results by index, it is often useful when the origin and type of document contain information relevant to your users. For example, a person searching for `shygirl` in a music streaming application is likely to appreciate seeing separate results for matching artists, albums, and individual tracks.
 
-Federated search is a better approach when the source of the information is not relevant to your users. For example, a person searching for a client's email in a CRM application is unlikely to care whether this email comes from chat logs, support tickets, or other data sources.
+Federated search is a better approach when the source of the information is not relevant to your users. For example, a person searching for a client's email in a CRM application is unlikely to care whether this email comes from chat logs, support tickets, or other data sources.

learn/multi_search/federated_search_guide.mdx → learn/multi_search/performing_federated_search.mdx

@@ -1,13 +1,13 @@
 ---
-title: Federated search guide — Meilisearch API reference
-description: 
+title: Using multi-search to perform a federated search — Meilisearch API reference
+description: In this tutorial you will see how to perform a query searching multiple indexes at the same time to obtain a single list of results.
 ---
 
-# Federated search guide
+# Using multi-search to perform a federated search
 
-A federated search is a multi-index search that returns results across multiple indexes in a single list.
+Meilisearch allows you to search in multiple indexes at the same time with the `/multi-search` endpoint. A federated search is a multi-index search that returns results across multiple indexes in a single list.
 
-In this guide you will see how to create separate indexes containing different types of data from a CRM application. You will then perform a query searching all these indexes at the same time to obtain a single list of results.
+In this tutorial you will see how to create separate indexes containing different types of data from a CRM application. You will then perform a query searching all these indexes at the same time to obtain a single list of results.
 
 ## Requirements
 
@@ -16,15 +16,17 @@ In this guide you will see how to create separate indexes containing different t
 
 ## Create three indexes
 
-Download the following datasets: <a href="/assets/datasets/crm-chats.json">`crm-chats.json`</a>, <a href="/assets/datasets/crm-profiles.json">`crm-profiles.json`</a>, and <a href="/assets/datasets/crm-tickets.json">`crm-tickets.json`</a> containing customer interaction data. Add them to Meilisearch, creating three separate indexes, `profiles`, `chats`, and `tickets`:
+Download the following datasets: <a href="/assets/datasets/crm-chats.json">`crm-chats.json`</a>, <a href="/assets/datasets/crm-profiles.json">`crm-profiles.json`</a>, and <a href="/assets/datasets/crm-tickets.json">`crm-tickets.json`</a> containing data from a fictional CRM application.
+
+Add the datasets to Meilisearch and create three separate indexes, `profiles`, `chats`, and `tickets`:
 
 ```sh
 curl  -X POST 'http://localhost:7700/indexes/profiles'  -H 'Content-Type: application/json'  --data-binary @crm-profiles.json &&
 curl  -X POST 'http://localhost:7700/indexes/chats'  -H 'Content-Type: application/json'  --data-binary @crm-chats.json &&
 curl  -X POST 'http://localhost:7700/indexes/tickets'  -H 'Content-Type: application/json'  --data-binary @crm-tickets.json
 ```
 
-Use the tasks endpoint to check the indexing status. Once Meilisearch successfully indexed all three datasets, you are ready to perform a federated search.
+[Use the tasks endpoint](/learn/async/working_with_tasks) to check the indexing status. Once Meilisearch successfully indexed all three datasets, you are ready to perform a federated search.
 
 ## Perform a federated search
 
@@ -80,9 +82,9 @@ Meilisearch should respond with a single list of search results:
 }
 ```
 
-## Promote results from an index
+## Promote results from a specific index
 
-Since this is a CRM application, it is likely your users have profiles where they specified their preferred contact information. If you want to search for Riccardo Rotondo's official preferred email, you can boost documents in the `profiles` index.
+Since this is a CRM application, users have profiles with their preferred contact information. If you want to search for Riccardo Rotondo's preferred email, you can boost documents in the `profiles` index.
 
 Use the `weight` property of the `federation` parameter to boost results coming from a specific index: