docs(createAutocomplete): rewrite docs (#472)

* docs(createAutocomplete): rewrite docs

* fix(createAutocomplete): fix links

* fix: apply suggestions from code review

Co-authored-by: François Chalifour <[email protected]>

Co-authored-by: François Chalifour <[email protected]>

packages/website/docs/createAutocomplete.md

@@ -2,12 +2,42 @@
 id: createAutocomplete
 ---
 
-This function returns the methods to create an autocomplete experience.
+Autocomplete Core exposes primitives to build an autocomplete experience.
 
-You're in charge of [creating your own autocomplete renderer](creating-a-renderer) with the returned API.
+The `createAutocomplete` function returns methods to help you create an autocomplete experience from scratch. This is fully headless: you're in charge of [creating your own autocomplete renderer](creating-a-renderer).
+
+:::info
+
+Building a custom renderer is an advanced pattern. You likely don't need it unless you've reached limitations with [`autocomplete-js`](autocomplete-js) and its templating capabilities.
+
+:::
+
+## Installation
+
+First, you need to install the package.
+
+```bash
+yarn add @algolia/autocomplete-core@alpha
+# or
+npm install @algolia/autocomplete-core@alpha
+```
+
+Then import it in your project:
+
+```js
+import { createAutocomplete } from '@algolia/autocomplete-core';
+```
+
+If you don't use a package manager, you can use a standalone endpoint:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@algolia/autocomplete-core@alpha"></script>
+```
 
 ## Example
 
+This example uses the package along with the [`algoliasearch`](https://www.npmjs.com/package/algoliasearch) API client and [`getAlgoliaHits`](getAlgoliaHits) function from the Autocomplete Algolia preset. It returns [a set of functions](#returns) to build an autocomplete experience.
+
 ```js
 import algoliasearch from 'algoliasearch/lite';
 import { createAutocomplete } from '@algolia/autocomplete-core';
@@ -44,20 +74,16 @@ const autocomplete = createAutocomplete({
 });
 ```
 
-## Import
-
-```ts
-import { createAutocomplete } from '@algolia/autocomplete-core';
-```
-
-## Options
+## Parameters
 
 import CreateAutocompleteProps from './partials/createAutocomplete-props.md'
 
 <CreateAutocompleteProps />
 
 ## Returns
 
+The `createAutocomplete` function returns [prop getters](prop-getters), [state setters](state#setters), and a `refresh` method that updates the UI state.
+
 ```js
 const {
   getEnvironmentProps,
@@ -76,5 +102,3 @@ const {
   refresh,
 } = createAutocomplete(options);
 ```
-
-This function returns the [prop getters](prop-getters), the [state setters](state#setters) and the `refresh` method that updates the UI state.

packages/website/docs/partials/createAutocomplete-props.md

@@ -8,25 +8,25 @@ The [sources](/docs/sources) to get the collections from.
 
 > `string` | defaults to `"autocomplete-0"` (incremented for each instance)
 
-The autocomplete ID to create accessible attributes.
+An ID for the autocomplete to create accessible attributes.
 
 ### `onStateChange`
 
 > `(params: { state: AutocompleteState<TItem> }) => void`
 
-Function called when the internal state changes.
+The function called when the internal state changes.
 
 ### `placeholder`
 
 > `string`
 
-The text that appears in the search box input when there is no query.
+The placeholder text to show in the search input when there's no query.
 
 ### `autoFocus`
 
 > `boolean` | defaults to `false`
 
-Whether to focus the search box when the page is loaded.
+Whether to focus the search input or not when the page is loaded.
 
 ### `defaultActiveItemId`
 
@@ -40,13 +40,13 @@ We recommend using `0` when the query typed aims at opening item links, without
 
 > `boolean` | defaults to `false`
 
-Whether to open the panel on focus when there's no query.
+Whether to open the panel on focus or not when there's no query.
 
 ### `stallThreshold`
 
 > `number` | defaults to `300`
 
-The number of milliseconds that must elapse before the autocomplete experience is stalled.
+How many milliseconds must elapse before considering the autocomplete experience [stalled](/docs/state#status).
 
 ### `initialState`
 
@@ -58,44 +58,44 @@ The initial state to apply when autocomplete is created.
 
 > `typeof window` | defaults to `window`
 
-The environment from where your JavaScript is running.
+The environment in which your application is running.
 
-Useful if you're using autocomplete in a different context than `window`.
+This is useful if you're using autocomplete in a different context than `window`.
 
 ### `navigator`
 
 > `Navigator`
 
-Navigator API to redirect the user when a link should be opened.
+An implementation of Autocomplete's Navigator API to redirect the user when opening a link.
 
-Learn more on the [Navigator API](/docs/keyboard-navigation) documentation.
+Learn more on the [**Navigator API**](/docs/keyboard-navigation) documentation.
 
 ### `shouldPanelOpen`
 
 > `(params: { state: AutocompleteState }) => boolean`
 
-The function called to determine whether the panel should open.
+The function called to determine whether the panel should open or not.
 
-By default, it opens when there are items in the state.
+By default, the panel opens when there are items in the state.
 
 ### `onSubmit`
 
 > `(params: { state: AutocompleteState, event: Event, ...setters }) => void`
 
-The function called when the Autocomplete form is submitted.
+The function called when submitting the Autocomplete form.
 
 ### `onReset`
 
 > `(params: { state: AutocompleteState, event: Event, ...setters }) => void`
 
-The function called when the Autocomplete form is reset.
+The function called when resetting the Autocomplete form.
 
 ### `debug`
 
 > `boolean` | defaults to `false`
 
-Whether to consider the experience in debug mode.
+A flag to activate the debug mode.
 
-It is useful when developing because it doesn't close the panel when the blur event occurs. This option should only be used during development.
+This is useful while developing because it keeps the panel open even when the blur event occurs. **Make sure to disable it in production.**
 
-See "[Debugging](/docs/debugging)" for more information.
+See [**Debugging**](/docs/debugging) for more information.

packages/website/sidebars.js

@@ -28,11 +28,6 @@ module.exports = {
     ],
     'API Reference': [
       'api',
-      {
-        type: 'category',
-        label: 'autocomplete-core',
-        items: ['createAutocomplete'],
-      },
       {
         type: 'category',
         label: 'autocomplete-js',
@@ -47,6 +42,11 @@ module.exports = {
           'reverseSnippetHit',
         ],
       },
+      {
+        type: 'category',
+        label: 'autocomplete-core',
+        items: ['createAutocomplete'],
+      },
       {
         type: 'category',
         label: 'autocomplete-plugin-recent-searches',