[DOCS] Documentation is not easy to use due to lack of easy navigation and overloading single pages

[lostpebble]

https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html

The new way documentation is presented on the site for some sections is basically one massive dump of information on a single page. This could work, but there is currently no sidebar or easy way to navigate around the different functionality. The only way to use it at the moment is to do a "find on page" or scroll endlessly until you find what you're looking for.

The previous way was to have each concept on a separate page, which was much easier to use because we could find the different pages on the right sidebar. But even that had its downsides because the sidebar was still static and stuck to the top of the page.

I'm not sure what caused the recent changes, but this is definitely a step back as far as usability goes for a user who is simply researching different ways to use the search request body functionality- or doing a quick skim to review functionality they have forgotten.

The areas I've noticed this most pronounced is the Search Request Body documentation, and the JavaScript client documentation (because I use these quite often) : https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/api-reference.html

Suggestion:

A fixed, scrollable sidebar which links to each header and sub-header for the current page's information. As well as a separate fixed sidebar for other documentation pages.

Google Cloud does this really well on their documentation site. For reference of what I'm talking about: https://cloud.google.com/bigquery/docs/reference/standard-sql/query-syntax

This makes life so much easier - I feel much more freedom in navigating the docs and have a much better overview of information at my finger-tips at all times. It definitely aids in learning and discovery of new ways to use the product.

[elasticmachine]

Pinging @elastic/es-docs (:Docs)

[debadair]

We are making changes to the API reference material to make things more consistent across the APIs, which is a good thing. However, this effort has highlighted some areas where simply applying the new API reference template doesn't go far enough. @jrodewig opened #48194 to discuss and track improvements to the search content that should address these issues.

We are in the process of redesigning the doc navigation experience. The fact that you can scroll past the navigation aids is particularly ugly. It helps to get feedback like this, and especially examples of what folks think works well (or doesn't).

[jrodewig]

[docs issue triage]

[jrodewig]

Closing in favor of elastic/docs#1340 and #48194