Elasticsearch: [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.

• [x] Create a "Search your data" chapter with high-level concepts and tutorials. #56058
• [x] Relocate our aggregations documentation after the "Search your data" chapter. #56058
• [x] 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. #55884, #56304
• [x] Move relevant examples from the current "Request Body" [2] chapter to relevant sections in the "Search your data" chapter:
  
  
  
  • [x] Fast check for any matching docs #60972
  
  
  • [x] Doc value Fields #57760
  
  
  • [x] Explain #56436
  
  
  • [x] Field Collapsing #60424
  
  
  • [x] From / Size #56785
  
  
  • [x] Highlighting #59768
  
  
  • [x] Index Boost #60972
  
  
  • [x] Inner hits #60840
  
  
  • [x] min_score #60895
  
  
  • [x] Named query clauses #60748
  
  
  • [x] Post filter #60903
  
  
  • [x] Preference #60972
  
  
  • [x] Query #56436
  
  
  • [x] Rescoring #60903
  
  
  • [x] Script Fields #60826
  
  
  • [x] Scroll #60515
  
  
  • [x] Search After #60515
  
  
  • [x] Search Type #60972
  
  
  • [x] Sequence Numbers and Primary Term #56436
  
  
  • [x] Sort #60123
  
  
  • [x] Source filtering #57689
  
  
  • [x] Stored Fields #60826
  
  
  • [x] Track total hits #60972
  
  
  • [x] Version #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.