[ES|QL][E&A] General improvements

[florent-leborgne]

The ES|QL docs are rapidly growing and require some attention to improve the overall UX:

• Relocate some content into the reference docs
• Assess and improve navigation paths between narrative and reference docs
• Update Get started and subsequent pages in narrative content to improve the learning journey about
  • the language itself
  • each interface that supports the language (incl. Kibana features)
• Review the usefulness and depth of the examples as more commands and functions are added to the language

cc @leemthompo as we spoke about this

[stratoula]

Can we add some docs for ES|QL controls too? They are much more improved in 9.1 cc @ghudgins

[florent-leborgne]

ES|QL controls are documented here: https://www.elastic.co/docs/explore-analyze/dashboards/add-controls#add-esql-control
And I'll edit these docs for 9.1 as part of #1679

[florent-leborgne]

Plan that we agreed on with @leemthompo to improve the user experience:

• Merge all pages in https://www.elastic.co/docs/explore-analyze/query-filter/languages/esql into the reference docs to have a complete doc set about ES|QL as a language at the same place
• Except these 2 very Kibana-specific pages: https://www.elastic.co/docs/explore-analyze/query-filter/languages/esql-kibana (to remain there as a child page of Query languages and focus on the ES|QL editor in Kibana) and https://www.elastic.co/docs/explore-analyze/query-filter/languages/esql-elastic-security (to simply remove and redirect to https://www.elastic.co/docs/solutions/security/esql-for-security)

(Elasticsearch repo changes landing in elastic/elasticsearch#133301)

Other ES|QL-related pages, for examples about dashboard controls or ES|QL visualizations will remain intact. This is only about the big chunk of pages under explore-analyze/query-languages/esql

[lcawl]

On a related note, I have a to-do to relocate https://www.elastic.co/docs/solutions/search/esql-search-tutorial since that "API quickstarts" section is going away. I was planning to start making plans for which new/useful content from that ES|QL API quickstart ought to go in:

• https://www.elastic.co/docs/explore-analyze/query-filter/languages/esql-getting-started
• https://www.elastic.co/docs/explore-analyze/query-filter/languages/esql-examples
• https://www.elastic.co/docs/solutions/search/semantic-search/semantic-search-semantic-text
• https://www.elastic.co/docs/solutions/search/get-started/semantic-search
• ...?

If I ought to defer this work until these general improvements are complete, lmk!

[leemthompo]

Hey @lcawl thanks for checking in about this

I was planning to start making plans for which new/useful content from that ES|QL API quickstart ought to go in

Re https://www.elastic.co/docs/solutions/search/esql-search-tutorial we shouldn't chop that up, it is self-contained and we don't want it in Explore & Analyze either, given the theme of this issue.

So we could either:

1. Keep it in docs-content/solutions/search or move it to the main ESQL docs. We could easily just rename "API quickstarts" to "Tutorials" if want to go the low-effort road, given that it's now just two longish tutorials (Query DSL + ESQL) that remain there after you've moved the basics quickstart out of that section.
2. I'd also be very happy to see it together with the rest of the ESQL docs per the work here, we've got a lot of needless scattering of related content in general today.

If it's the latter, I can handle it in my PRs for this issue.

Otherwise, unfortunately I think we need to think long and hard about whether all of the content in solutions/search shouldn't just be re-homed to the elasticsearch repo, considering the scattering of those docs is sub-optimal for readers and contributors alike 😬