Replicate some /guide navigation experience in Reference section of /docs

[KOTungseth]

Description

We have received feedback that the new goal-based structure makes it difficult for users who are accustomed to the /guide product-based navigation.

The reorganization around user tasks rather than products has disrupted how many users search for and consume documentation.

For example, users managing specific clusters or studying for certifications struggle to find the right documentation.

Solution

Restore a familiar experience by replicating the elastic.co/guide/index.html structure at elastic.co/docs/reference, mirroring the navigation used in versions 8.18 and earlier.

Proposed tasks

• Create a dedicated Elastic APIs page
• Pull the following into Elasticsearch:
  - Text analysis: Built in analyzer, Tokenizer, Token filter, Characters filter, Normalizers
  - Ingest processor
  - Aggregations
  - Query languages ?
  - Search connectors ?
  - Search UI ?
• Pull Infrastructure app metrics reference content into Elastic Observability section
• Pull Kibana Query Language and Canvas functions into Kibana section
• Create a new Machine learning page and pull in the following:
  - Supplied configurations
  - Analysis functions
• Pull all Logstash content into a dedicated Logstash section
• Reorganize the Reference landing page to replicate the /guide docs landing page

Landing page restructure

Elasticsearch
Elasticsearch reference
Elasticsearch APIs
Elasticsearch Serverless APIs
Elasticsearch Clients
Elasticsearch for Apache Hadoop
Curator Index Management
Painless scripting language
Elasticsearch plugins

Elastic Observability
Elastic Observability reference
Elastic Distributions of OpenTelemetry (EDOT)
APM
APM Server APIs
Observability intake Serverless APIs

Elastic Security
Elastic Security reference
Elastic Security APIs

Elastic Stack
Elastic Common Schema (ECS)
Kibana
Kibana APIs
Kibana Serverless APIs
Machine learning (new page)

Ingest
Fleet and Elastic Agent
Elastic integrations
Logstash
Logstash APIs
Logstash Plugins
Logstash Versioned Plugins
Beats
Auditbeat
Filebeat
Heartbeat
Metricbeat
Packetbeat
Winlogbeat
Elastic logging plugin for Docker
Elastic Serverless Forwarder for AWS

Cloud
Elastic Cloud Hosted
Elastic Cloud Hosted APIs
Elastic Cloud Serverless APIs
Elastic Cloud Enterprise
Elastic Cloud Enterprise APIs
Elastic Cloud on Kubernetes
Elastic Cloud on Kubernetes APIs
Elastic Cloud billing APIs
Elastic Cloud Control (ECCTL)

[leemthompo]

The reorganization around user tasks rather than products has disrupted how many users search for and consume documentation.
For example, users managing specific clusters or studying for certifications struggle to find the right documentation.

Some thoughts:

• I think degraded search is the dominating factor for these issues rather than the IA TBH.
• I think the perceived negative UX delta versus the 8.x docs is probably more about chunks of content moving out of the product-based references into docs-content rather than the structure of the new references (also compounded by degraded search).
  • But this was a very considered decision that we either stand by or we don't. We won't solve that component by reshuffling the new reference structure.
• I do agree that we can improve the new reference structure, but I'm not sure if the ROI will be super high.

[florent-leborgne]

If these issues extend to narrative docs, there may be ways to also get the narrative content IA closer to product-based navigation while still embracing our new docs approach and IA.

Some sources of confusion I've witnessed while showing the new docs around and that the overall feedback received sometimes indicate too:

• Explore & Analyze mixing Kibana and Elasticsearch while not clearly identifying them
• Elasticsearch content distributed between solutions, explore and analyze, and reference docs
• Lack of bridges between Kibana and solution docs (that already existed before)
• No centered view on managing specific deployments types

Some possible solutions for these could be:

• Build more recipe-like docs to provide alternate views that match the way users may approach the docs
• Improve the way we identify tools/components on our docs pages
• Move some things around. For example, bring Kibana analytics general docs closer to solution docs or split them more clearly from Elasticsearch core concepts

[ppf2]

We should also address the overall navigation experience where we are requiring the user has to first make a decision point to pick where they want to go.

Once they have picked their main path, they are pretty much drilled down into that topic with its own navigation menu.

From there, they lose track of what else (e.g. Reference) is available that may be helpful as they read about their specific topic.

It can be helpful to have all the top level entries in the dropdown always available in the left Navigation (just collapsed) regardless of which top level topic they have already drilled down to so that users can easily navigate and expand other topics like Reference (now that we have separated out the "use cases" from the reference information).

I suspect this is one of the common reasons users are using the Search box more these days which has its own challenges.

[georgewallace]

@leemthompo can you please provide a status of where this initiative is in the process so I can add it to the bi-weekly agenda? Please let me know

Current Status:
Next Steps:
Any blockers / help needed: