[DOCS] Reorganize search content

[jrodewig]

#48189 notes that the current search docs organization is a bit messy and hard to navigate.

Where possible, we should streamline this documentation. I've outlined a proposal below. Any feedback is welcome.

• Create a "Search your data" chapter with high-level concepts and tutorials. [DOCS] Create top-level "Search your data" page #56058
• Relocate our aggregations documentation after the "Search your data" chapter. [DOCS] Create top-level "Search your data" page #56058
• Combine the "Search" [1], "Request Body" [2], and "URI Search" [3] chapters into a single "Search API" reference chapter as this is actually a single (but big) endpoint. [DOCS] Combine search API and URI search API reference docs #55884, [DOCS] Relocate search API's request body parameters #56304
• Move relevant examples from the current "Request Body" [2] chapter to relevant sections in the "Search your data" chapter:
  • Fast check for any matching docs [DOCS] Remove search request body page #60972
  • Doc value Fields [DOCS] Move search API's docvalue_fields examples #57760
  • Explain [DOCS] Relocate request body param docs to search API docs #56436
  • Field Collapsing [DOCS] Move field collapse content to separate page #60424
  • From / Size [DOCS] Add search pagination docs #56785
  • Highlighting [DOCS] Move highlighting docs to separate page #59768
  • Index Boost [DOCS] Remove search request body page #60972
  • Inner hits [DOCS] Move inner hits content to separate page #60840
  • min_score [DOCS] Move min_score docs to search API page #60895
  • Named query clauses [DOCS] Move named query content to bool query #60748
  • Post filter [DOCS] Move post filter/rescore content to new page #60903
  • Preference [DOCS] Remove search request body page #60972
  • Query [DOCS] Relocate request body param docs to search API docs #56436
  • Rescoring [DOCS] Move post filter/rescore content to new page #60903
  • Script Fields [DOCS] Move script and stored fields content to search fields page #60826
  • Scroll [DOCS] Move search pagination content to one page #60515
  • Search After [DOCS] Move search pagination content to one page #60515
  • Search Type [DOCS] Remove search request body page #60972
  • Sequence Numbers and Primary Term [DOCS] Relocate request body param docs to search API docs #56436
  • Sort [DOCS] Move search sort docs to separate page #60123
  • Source filtering [DOCS] Move source filtering examples #57689
  • Stored Fields [DOCS] Move script and stored fields content to search fields page #60826
  • Track total hits [DOCS] Remove search request body page #60972
  • Version [DOCS] Relocate request body param docs to search API docs #56436

[0] https://www.elastic.co/guide/en/elasticsearch/guide/master/search-in-depth.html
[1] https://www.elastic.co/guide/en/elasticsearch/reference/master/search-search.html
[2] https://www.elastic.co/guide/en/elasticsearch/reference/master/search-request-body.html
[3] https://www.elastic.co/guide/en/elasticsearch/reference/master/search-uri-request.html
[4] https://www.elastic.co/guide/en/elasticsearch/reference/master/modules-cross-cluster-search.html

[elasticmachine]

Pinging @elastic/es-docs (>docs)

[elasticmachine]

Pinging @elastic/es-search (:Search/Search)

[jrodewig]

Adding the team-discuss tag as I'd like feedback before getting started.

[lostpebble]

Would just like to emphasize a little, as I don't see it really mentioned and wouldn't like it to be overlooked, that my biggest gripe isn't so much the messiness of it - it's more the lack of ability to navigate easily between API concepts and have a good overview of the documentation at my disposal at all times. The documentation itself is generally fine.

That said, those changes you mention all sound like great things as well- things I would have definitely appreciated more of when I was first starting out. Though the actual referencing of concepts is my main documentation usage now.

I really recommend checking out how Google Cloud structures things to understand where I'm coming from (https://cloud.google.com/bigquery/docs/reference/standard-sql/query-syntax):

• Nice, broad documentation navigation on the left
• Contextual navigation to the current page on the right

[jrodewig]

Thanks @lostpebble. I agree; I don't believe these changes will completely solve your issue.

Changing the navigation layout will require a larger, separate effort. That's on our radar, but it won't be addressed in the scope of this issue.

[jrodewig]

[docs issue triage]

[jtibshirani]

This seems like a great effort that will really help cut down on confusion.

In my own experiences with the search docs, I've found it hard to navigate the different options in the search request:

• I usually consult the search request body page as a reference on search options. It's huge page containing every option, so I need to 'ctrl-f' to find the section I'm looking for. It feels overwhelming and it's easy to lose my place and end up in a different section.
• The sections aren't grouped together by theme. For example, docvalue_fields, source filtering, and script_fields are split apart. It's hard to know what's available and compare options.

Some ideas:

• In the short-term, perhaps making these into collapsible sections could help?
• Some sections seem like good candidates for their own page. For example, the highlighting section is extensive and could be a separate subpage.
• We could group certain options together in terms of their use like 'Returning field values from a search'. Perhaps this would fit best as sections of the 'search your data' reference.