Make the "help" button on generated rustdoc pages easier to find

[jyn514]

I've talked to 3+ experienced rust developers this morning, all of whom were unaware of the existence of the help popup. They mentioned the following issues:

• The icon is to the right of search, not the left, making it seem unimportant.
• The icon is smaller than the search bar, making it seem unrelated.
• They've been trained by microsoft products that ? is useless and doesn't have any non-trivial amount of info.

We should move the icon to the left and make it larger. They also suggested duplicating the help text on the docs.rs homepage, which seems like a much bigger hammer, but maybe is worth considering.

cc @rust-lang/rustdoc

Yes, I think it would be helpful to show some help text in multiple places. The search tricks of the help could be added to the No results :( page and the other half (the keyboard shortcuts) could be shown somewhere else as well maybe.

And I think '?' for more options... in the search bar should be changed to press '?' for help....

[camelid]

Yeah, I often forget about the help button myself, even though I know we have one ;)

We should move the icon to the left

But then it'll no longer be next to the config icon, right?

[jyn514]

We could move both icons at the same time.

[GuillaumeGomez]

Fine by me!

[camelid]

We could move both icons at the same time.

It is weird that the theme icon is on one side and the others are on the opposite side, so moving all of them together sounds good.

[jsha]

I'd like to break this down into sub-problems:

Problem 1: Experienced Rust Developers don't know about the help popup.

Problem 2: Experienced Rust Developers don't know about the things the help popup teaches them, specifically:

• Problem 2a: They don't know about the keyboard shortcuts.
• Problem 2b: They don't know about the search tips.

Keyboard Shortcuts

? Show this help dialog
S Focus the search field
T Focus the theme picker menu
↑ Move up in search results
↓ Move down in search results
← / → Switch result tab (when results focused)
⏎ Go to active search result
+ Expand all sections
- Collapse all sections

Search Tricks

Prefix searches with a type followed by a colon (e.g., fn:) to restrict the search to a given item kind.
Accepted kinds are: fn, mod, struct, enum, trait, type, macro, and const.
Search functions by type signature (e.g., vec -> usize or * -> vec)
Search multiple things at once by splitting your query with comma (e.g., str,u8 or String,struct:Vec,test)
You can look for items with an exact name by putting double quotes around your request: "string"
Look for items inside another one by searching for a path: vec::Vec

---

In other words, almost all of the help popup is actually help about searching. We should present that information to people when it is most relevant: when they are searching. A quick mockup:

That can do a more effective job teaching people about the search syntax and the search-related keyboard shortcuts, while reducing overall clutter. Excessive clutter around the search bar was one of the major themes of #59829. We should be aiming to remove elements surrounding the search bar rather than add more. For instance, in #84539 I propose that the paintbrush icon should be replaced with equivalent functionality in the settings menu, since picking a theme is a rare operation.

If we use the search page to teach people about searching, we need to teach people about the remaining keyboard shortcuts:

/ to focus search (this is described in the grey text inside the search box, so we're good)
T to focus theme picker (this will be reachable in the settings menu with normal navigation)
- / + to expand all / collapse all. We should advertise these in the hover text for the [-] icon at the top of the page. If people aren't aware of that icon or what it does, that's an additional problem we should solve.

@jyn514 when you talked to those Rust devs, what was the functionality you wanted them to know about inside the help popup?

[jyn514]

@jsha 2b, the search tips - this originally came up because someone suggested adding a ref:MyType search syntax, not realizing that functionality is already available from the "In Parameters" and "In Return Types" tab of search.

[camelid]

That can do a more effective job teaching people about the search syntax and the search-related keyboard shortcuts, while reducing overall clutter.

IMO, that adds more clutter, since it's a whole sentence that'd appear every time you use the search box and distract from the search results.

We should be aiming to remove elements surrounding the search bar rather than add more. For instance, in #84539 I propose that the paintbrush icon should be replaced with equivalent functionality in the settings menu, since picking a theme is a rare operation.

I agree that we should reduce the number of elements, but I disagree that picking a theme is a rare operation. Since docs.rs does not persist settings across crates, because that's managed by rustdoc, I have to manually change the theme if I want to put the page in dark mode. Perhaps one way to mitigate this would be to make following the system theme the default setting—but then, since I prefer Ayu over the Dark theme, I'd still have to dig around in settings to switch the default dark theme to Ayu.

[jyn514]

Since docs.rs does not persist settings across crates, because that's managed by rustdoc

Wait, what? We spent a long time making sure the theme syncs across pages, it even applies to the docs.rs homepage.

[camelid]

Since docs.rs does not persist settings across crates, because that's managed by rustdoc

Wait, what? We spent a long time making sure the theme syncs across pages, it even applies to the docs.rs homepage.

I stand corrected! Wow, did that happen recently? I remember it not being synchronized... Anyway, that's amazing!

[jsha]

IMO, that adds more clutter, since it's a whole sentence that'd appear every time you use the search box and distract from the search results.

My intent with the mockup was that there would be an easy, obvious button (mimicked with "[x]") that dismisses the tips forever.

this originally came up because someone suggested adding a ref:MyType search syntax, not realizing that functionality is already available from the "In Parameters" and "In Return Types" tab of search.

It sounds like this is a third problem: people aren't noticing the "In Parameters" and "In Return Types" tabs of search, or notice them but don't internalize what they do. I think making the help popup more prominent doesn't actually solve this problem, right?