Discoverability issues in the docs - some content is hard to find

[jbw976]

What's Wrong?

I'm finding some content in the docs to be difficult to discover/find. They are broken out into sections below.

Are search results the best they can be?

I have a feeling that the results from our algolia search are not 100% what users are looking for when they type in keywords. @lsviben was searching for composition debugging information recently using "debug" as his search term and could not find it.

Can the search results be improved?

• Are we able to look at metrics for the most popular search terms and then manually influence the result weighting etc. so that the truly best docs are returned?

Navigation Pane is dynamic

The left hand navigation pane (table of contents) dynamically changes depending on which high level section of the docs site you are on. User Documentation, Knowledge Base, and Contributing Guide all have 3 entirely different navigation panes, and while clicking around the site and through different areas feels a bit jarring and disorienting because the nave pane does not stay static.

• Can the nave pane stay static and consistent no matter where you are on the site?

Configuration Guides is a misleading catch-all

The "Configuration Guides" section appears to be a bit of a catch-all for all types of content, even if they aren't really a guide for configuring the system.

I feel like a lot of people may look at the Configuration Guides entry in the left-hand navigation pane, especially because it isn't expanded by default, and not expect to find things like our Feature Lifecycle or Troubleshooting page.

Is there a way we can make some of this good content more discoverable?

• make a new top level section that is a better home than Configuration Guides is
• Expand Configuration Guides section by default in the nav pane, so people can see it more easily.

expand shortcode blocks are easy to miss

The expand shortcode is used to hide blocks of text by default. However, in practice these blocks are really easy to miss when reading or scanning a doc, so I think the content hidden by them very rarely gets viewed.

A specific case where this hurts is when a search result is hidden in one of these blocks. e.g. searching the docs for EnvironmentConfig yields one page result that takes you to https://docs.crossplane.io/latest/software/install/. If you then use your browser to "find on page", you get 0 results. EnvironmentConfig looks to not actually be on that page at all, but it's actually hidden underneath the "feature flags" expand block.

• Can the expand blocks be made more visually noticeable?
• Can content in the expand blocks be automatically expanded if coming from the search results?

[plumbis]

There is some active design work in progress to update the design and information architecture that should help address points 2 and 3.

To point 1, there are known problems with the search results, the two big ones:

• The entire Composition page isn't indexed by search because it's too big (the large YAML outputs are the main problem)
• Search results aren't properly optimized

The /concepts sections is currently undergoing a full rewrite. The first part of the Composition page is nearly done, but the current content is being broken out into 6 unique pages.

Improving the content chunking, headings and metadata (Hugo description) will go a long way to improve search results but also this is an area I need help. I'm far from an expert in algolia and I don't have the JS knowledge to help improve the current search results.

[jbw976]

I think most all of my complaints have been addressed or are now further tracked in remaining issues:

• Improve expand box ("accordion") visibility #480
• Improve Search #645
• Proposal: Remove and Reorg Knowledge Base #749