documentation
documentation copied to clipboard
Add asynchronous operations to core concepts
The asynchronous API is a core part of the experience of using Meilisearch. We want to make sure that new users—especially ones who have never before used an async API—have the opportunity to understand this concept before running into it as a roadblock in their development.
First, there's the conceptual layer: understanding that some methods are asynchronous and will not complete immediately. Then there's the practical layer: understanding where to find the taskUid
and how to query the /tasks
API to confirm its status
.
The Asynchronous Operations page will require some reformatting to fit in the core concepts section. This means we have a choice: do we split this page in two—one conceptual page in core concepts, one practical page in advanced guides—or do we keep all the information together in one page?
The latter would effectively be a departure from the stated goals of the core concepts section (in a phrase, to be conceptual). But as @maryamsulemani97 noted in #1333 , many documentation sites with similar sections combine a conceptual and practical approach. It would likely be more effective to give new users a holistic view of the async workflow, rather than introducing them to the concept and then asking them to navigate elsewhere for more information.
A decision like this has to do with our knowledge architecture. Up to this point, we have aimed to keep our API references clean and focused on the API; to make our guides comprehensive w/r/t to usage and granular edge cases; and to offer concept explanations that focus more on understanding than accuracy/efficiency. Based on this paradigm, it makes sense to split asynchronous operations into a tasks guide and an async operations explanation.
Related to #1273