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

[wooster0]

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?

[camelid]

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

How hard would it be for docs.rs to synchronize that between all crates like (I've now learned) it does for themes? Also, for locally built docs, you'd have to manually dismiss it each time you built the docs, which seems frustrating.

[jsha]

How hard would it be for docs.rs to synchronize that between all crates like (I've now learned) it does for themes?

Presumably not too hard, though @jyn514 can answer for sure. I agree it would be annoying if it wasn't synchronized!

Also, for locally built docs, you'd have to manually dismiss it each time you built the docs, which seems frustrating.

We should turn the tips off when accessing via file:// URLs.

[camelid]

Also, for locally built docs, you'd have to manually dismiss it each time you built the docs, which seems frustrating.

We should turn the tips off when accessing via file:// URLs.

That would solve the problem, but it feels like it adds complexity to rustdoc's behavior and could be confusing, though I guess it couldn't be too bad...

[jyn514]

I think making the help popup more prominent doesn't actually solve this problem, right?

Well, sort of - we have a link to doc.rust-lang.org/rustdoc in the popup and we could add some more docs there (#90309). But I agree it doesn't solve the problem on its own.

[GuillaumeGomez]

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

I did it a few months ago. :)

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

Let's avoid that. I think showing a sentence which would open the popup is a good idea. People will simply ignore it after a few uses of the rustdoc search.

We should turn the tips off when accessing via file:// URLs.

Let's not. Having different behaviours between local and non-local documentation is not a good idea at all.

Well, sort of - we have a link to doc.rust-lang.org/rustdoc in the popup and we could add some more docs there (#90309). But I agree it doesn't solve the problem on its own.

It would only work if you have an internet connection, so not the best. I think the current way is fine. It's how we allow people to get to it which needs to be refined.

[jyn514]

@GuillaumeGomez I have trouble understanding this comment:

It would only work if you have an internet connection, so not the best. I think the current way is fine. It's how we allow people to get to it which needs to be refined.

Right now we don't document the search tabs at all.

[GuillaumeGomez]

I meant going to <doc.rust-lang.org/rustdoc>. If we add more information, only "non-vital" should be put outside of rustdoc as much as possible.

Right now we don't document the search tabs at all.

True, which isn't great...

[camelid]

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

Let's avoid that. I think showing a sentence which would open the popup is a good idea. People will simply ignore it after a few uses of the rustdoc search.

We should turn the tips off when accessing via file:// URLs.

Let's not. Having different behaviours between local and non-local documentation is not a good idea at all.

I agree that having different behaviors between local and non-local docs could be confusing, but I also don't think unconditionally showing the sentence is a good idea either. It's hard to find the right balance here.

[Nemo157]

Presumably not too hard, though @jyn514 can answer for sure. I agree it would be annoying if it wasn't synchronized!

Since docs.rs is a single domain all local storage settings get shared across all documentation. As long as different versions of rustdoc are consistent in the settings they read/write they will synchronize the settings fine.