feat: inline documentation within the configuration file

[sarahdayan]

Summary

This PR attempts at bridging the gap between the project's configuration file and the documentation. The goal is for users to find the information they need more intuitively, and build a working implementation frictionlessly.

Check out the new config file →

The problem

When we did user research, we realized that many people directly go into editing the configuration file, without referring to the documentation. Depending on their level of Algolia/InstantSearch knowledge, they make assumptions. Still, there are grey areas that remain, and we realized that almost nobody tries browsing the documentation to find answers.

In almost all cases, nobody was able to put together a working implementation.

What it tells us is twofold:

1. We need better, more explicit errors in development mode.
2. We need to bridge the gap between the configuration file and the documentation.

@francoischalifour and I already have a plan for the first issue. This PR addresses the second problem.

The solutions

Since people have to edit the configuration file, we need to bring the knowledge here. We don't want to move the entire documentation in the configuration file or duplicate documentation data and have to maintain it twice. Instead, provide essential information and links to precise sections of the documentation that relate to what people are editing at a given moment.

To do so, we break the file down into several logical sections:

• Base configuration
• Insights, Analytics, and Personalization
• Sort-by
• Refinements
• Query Suggestions
• Styles

We introduce each section with a paragraph that provides essential information and a short link to the documentation's relevant part.

This model is heavily inspired by the TailwindCSS v0.x configuration file. With this solution, we increase documentation discoverability and optimize the back-and-forth between the editor and the docs by redirecting people to the right place.

To do before we release

This PR isn't ready to merge. Before doing so, if we agree with the model, we need to:
1. Adapt the documentation accordingly. We can't create short link redirects to anchor links, so we need to break options down into several pages. Done!
2. Generate alg.li short links once we have the final documentation URLs. Done!

Once we're good on the model and format, we can take care of these two steps, then merge the PR.

[seafoox]

I love the idea - great iteration.
Something I noticed with the current config file is that some people are not clear what value to change with their own due to the fact we provide an already filled config file. What do you think of the idea of providing by default an empty one, and providing the filled one (current one) in addition as an example?
Maybe we could have in the command line a command "run demo" that uses our config file instead of their own.

WDYT?

[sarahdayan]

@seafoox Hmmm, I'm not sure. With an empty configuration file, there are many things that users may miss and I'm afraid that:

1. They forget a mandatory setting and they try running the demo only to see it fail.
2. They don't intuitively understand what to change a demo value with and they need to go to the documentation too much while they could have picked on the example instead.
3. They will miss on features.

For example, right now we have this for the base configuration:

export const inputContainer = '#search-button';
export const inputContent = 'Search for products';
export const keyboardShortcuts = ['/'];
export const appId = 'latency';
export const searchApiKey = '6be0576ff61c053d5f9a3225e2a90f76';
export const hitComponent = Hit;
export const index = {
  indexName: 'instant_search',
  searchParameters: {
    analytics: true,
    clickAnalytics: true,
    hitsPerPage: 18,
    attributesToSnippet: ['description:25'],
  },
};

If we empty it, we'll may have something like this:

export const inputContainer = '';
export const inputContent = '';
export const keyboardShortcuts = [];
export const appId = '';
export const searchApiKey = '';
export const hitComponent = Hit;
export const index = {
  indexName: '',
  searchParameters: {},
};

Here, I don't have a clear idea of what options like inputContainer, inputContent, or keyboardShortcuts must contain. If I'm new to Algolia, I don't even know what appId, searchApiKey and index.indexName are about. Additionally, if I go through and run the demo successfully, I may not pay much attention to index.searchParameters and miss out on critical search parameters such as analytics and clickAnalytics.

If we still provide an example config in addition to the empty one, I think we're adding complexity instead of making things easier.

Do you have examples of what users found hard to understand or didn't know how to change (or if they had to at all)? I'm wondering if this isn't something we should fix with better docs instead.

[seafoox]

@sarahdayan Actually, re-reading the thread I realize I was more thinking about something in between. Where some values could stay by default like the keyboardShortcuts or inputContent to only name those two, and the one we expect the user to change at the first place to be replaced by explicit placeholders eg YOUR_SEARCH_INPUT_HERE with an inline example if relevant.

export const inputContainer = 'YOUR_SEARCH_INPUT_HERE'; // e.g #search-button
export const inputContent = 'Search for products';
export const keyboardShortcuts = ['/'];
export const appId = 'ALGOLIA_APPID';
export const searchApiKey = 'ALGOLIA_SEARCH_ONLY_API_KEY';
export const hitComponent = Hit;
export const index = {
  indexName: 'instant_search',
  searchParameters: {
    analytics: true,
    clickAnalytics: true,
    hitsPerPage: 18,
    attributesToSnippet: ['description:25'],
  },
};

As for the different widgets we use, they could be by default commented, and for the users to un-comment them along the way. Allowing them to get something working with minimal configuration, where today it often fires errors in the JS console.

Do you have examples of what users found hard to understand or didn't know how to change (or if they had to at all)? I'm wondering if this isn't something we should fix with better docs instead.

I think remember Marine mentioning something on that, but it was already a few weeks ago, and my memory might be playing tricks on me.

[sarahdayan]

@seafoox Okay I see! This is definitely interesting. With such an approach, we could indeed have two files: one for users to change with more explicit placeholders, and the fully pre-filled one with the data from the latency app. We could then have a demo command if people want to see a working example with that data.

Let's tackle this in another PR so we can elaborate and share ideas there.

[sarahdayan]

Okay, the documentation is updated and the short links are ready. This can be reviewed.

I'll change the link to the config file to settings.js in the docs as soon as we release.

cc @francoischalifour

[seafoox]

LGTM - good job

[seafoox]

Sounds good thanks -- [image: Alexandre COLLIN Avatar] [image: Algolia's logo] <https://algolia.com/> *Alexandre COLLIN* Data & Program Manager - Customer Care alexandre.collin@algolia.com [image: LinkedIn icon] <https://www.linkedin.com/in/alexandrecollin/> [image: GitHub icon] <https://github.com/seafoox> [image: Twitter icon] <http://twitter.com/alexandrecollin> For details about what personal information we collect and why, see our Privacy Policy at https://www.algolia.com/policies/privacy

…

On Mon, Jul 27, 2020 at 12:49 PM Sarah Dayan ***@***.***> wrote: Okay, the documentation is updated and the short links are ready. This can be reviewed. I'll change the link to the config file to settings.js in the docs as soon as we release. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#139 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAIM3JGX2ZFBSZDDPPXI6W3R5VLS3ANCNFSM4PF4SSOQ> .

[francoischalifour]

Great!