Restructure site

[dichotommy]

It has been a year since our previous site restructure, and we have learned much. Now it's that time again... ☃️

You just restructured your site a year ago, why do it again now?

1. No more hidden content: long live the single sidebar

After conducting a survey with the Meili developer team and some top contributors, we have come to understand that our current structure of three unique sidebars accessible from top navbar links leads to too much information siloing. For example, a user might look for a certain article in the "Reference" section and come to the conclusion that it doesn't exist, when it is in fact present in the "Learn" section.

Other complaints we received state that clicking links and being taken to a different page with a completely different sidebar can be disorienting. We would rather users know where they are in the site at all times and how to get back there easily. Moving away from top navbar links and towards a single sidebar should also mean fewer clicks to access information, and allow users to have a quick overview of all the kinds of information contained in the docs.

In other words, all of the data we currently have (which is not much) suggests that experienced developers prefer to have a single sidebar on documentation sites! So we will move forward in this direction 🚀

For a reference, have a look at the Tailwind docs.

2. Eliminate our last content dumping grounds

Every site heavily involved in organizing large amounts of content probably ends up with a "dumping ground" eventually: some place to throw all the content that doesn't fit into existing categories. Whether it's called "miscellaneous" or "FAQ", this is a bad practice that gets worse if unaddressed.

Ours is called "Feature References", and it's time to deal with it once and for all.

The articles in this section contain extremely valuable content, but it is poorly organized and presented, creating a barrier for users. We will move, split, rename, and/or rewrite these articles so that the information is more accessible.

3. Smaller improvements

While we're moving towards a single sidebar and eliminating the content buildup in the "Feature References" section, we will take care of some much-needed organizational improvements before the move to Docusaurus. For example:

• Change the name of the "Create" section: possibly to "Cookbooks". Nobody knows what "Create" means. It's not intuitive.
• **Bring "Under the Hood" section back into the sunshine: it's too hidden
• Adjust top navbar links: return FAQ to its rightful place, add a clearly labeled "SDKs" dropdown, etc.
• Improve the comprehensiveness and redundancy of the API references section to support developers whose first instinct is to head directly there and never leave 😶
• Remove useless "table of contents" pages, i.e. the big links in the sidebar: only a few of these are actually useful (e.g. What is MeiliSearch, API References) and the rest just serve to briefly explain the section, and go out of date every time we add a new page and forget to update the TOC

Implementation

Distribute content from "Feature references" into other sections

• "Guide-like" content (e.g. Dumps, Geosort, Filtering and Faceted Search) can be moved as is into the "Advanced Guides" section.
• "Reference-like" content (e.g. Search parameters, Settings, Configuration) should be incorporated into the API reference.
• Other content (e.g. Language, Web Interface, Errors) should be treated on a case-by-case basis.
• A sub-goal of this task is to reduce the number of pages in the docs with the same name (e.g. Settings, Dumps). Many of the articles currently in Feature References should have more descriptive names after the move.

Move to two sidebar display

• During the transition we will aim for two sidebars: one for API references, and one for everything else.
  • We can take some time to test this out and determine if it works better for us than a single sidebar
• Reference for a one-sidebar display: Tailwind's docs
• Reference for a separate API sidebar: Stripe's API reference

Move "Under the Hood" to Learn

Move "Create" content to Learn and re-title this subsection "Cookbooks"

• This content will eventually be moved into the Resource Center
• All articles relating to external technologies should have a clear owner outside the Documentation team, responsible for updating that article. These will be added to a list in our internal documentation (Notion).
• Articles without an owner should be retro-published on the blog and removed from the docs (e.g. out-of-date React guide)
• If staying on the documentation site, all "blog post"-like elements should be removed (e.g. introduction of Running MeiliSearch in Production) and style made consistent with other "Cookbooks"

Adjust top navbar links

• Add FAQ back to top navbar
• Give SDKs their own dropdown menu titled "SDKs"
• Remove "Create"
• Add an "Ecosystem" dropdown including our GitHub, Slack, main landing page, blog, and Awesome MeiliSearch repo.
• Consider further changes

Treat API references landing page as second homepage

• Repeat critical information here, with numerous links to other parts of the docs:
  • How async updates work
  • Where to find guides
• Understand that this will be the landing point for many experienced developers.

Finally, retitle Learn and consider getting rid of the landing page! It adds unnecessary clicks to viewing the sidebar with all of the content.

Don't forget to add redirects!

This one is a given.

[guimachiavelli]

What do you think about breaking this issue down into smaller ones? Perhaps it's more of a project than an issue, actually?

It's hard to discuss and to act on so many things grouped together in a monolith issue, IMHO.

[dichotommy]

Completed by #1436 , with just a few remaining tasks in #1452