Please bring back the paintbrush icon, or an equivalent! #93216
Comments
rustbot
added
the
T-rustdoc
|
Hi @steffahn! Thanks for the detailed feedback. For additional context, these changes are also largely motivated by:
The overall theme is that a lot of visual clutter harms readability - particularly for readers with dyslexia, and also particularly for new users. The paintbrush icon is one of the things I have heard the most complaints about - it occupied an enormously prominent position on every single documentation page, for what is -- in most cases -- a one-time operation.
This is definitely an issue, and will be fixed by #93097. That PR will also add the "Escape" button as a hotkey to leave the settings menu, going back to the page you were on. Another really nice improvement we could make here - instead of a drop-down, theme selection should really be a radio button interface, so the themes are all visible when you first open the page, and it takes only a single click to set one. By the way, you may be interested in the "Rustdoc settings sync" add-on by @notriddle: https://chrome.google.com/webstore/detail/rustdoc-settings-sync/bjlannnpljhejnbhnjghmamhidbcbhgm This will automatically sync your settings across doc.rust-lang.org, docs.rs, and localhost, hopefully saving some more clicks. @notriddle, what do you think of adding some of the more popular third-party rustdoc sites, like doc.serde.rs? |
|
No, I am not installing a browser extension just because rustdoc decides to make its theme setting unworkable without an extension that would fix it! And extensions aren't even a solution for all mobile browsers, or help when switching devices. Browser extensions can be great for websites of stubborn companies that regularly decide to kill user experience for whatever reason nobody asked for, nobody understands, and where user feedback isn't taken into account. (If you couldn't tell, I'm not happy with what kind of BS YouTube is pulling off at the moment, just that their BS can't even be fixed with browser extensions.) Before I recently installed "dark reader" extension, rustdoc and mdbook were the only websites I've been using that had a comfortable to use approach to dark themes. Now, only mdbook is left. If high contrast of the paintbrush or its location are a problem, move the symbol or lower its contrast. I seriously cannot imagine any solution to theme selection that I wouldn't consider worse in user experience, other than a dedicated, visible by default theme picker drop down menu (labeled with an icon or text that suggests this is about themes/appearance). The degree of "how much worse" of course varies, the current solution is about as bad as it gets. Also, anything that requires more than 2 clicks or has the intermediate effect of (visually) taking you to an entirely different page, seems particularly annoying. #93097 doesn't fix any of this. Take a look at https://meta.discourse.org for a website that has an acceptable, but not great approach to themes. Pros: you can change themes in the hamburger menu without being logged in, with 2 clicks, and without taking you to a different page. Cons: still hard to discover, especially if you're not searching for it. (Note that I don't share the opinion that it's too high contrast or in a bad location. Moving it will force existing users to search for it again, and a different contrast might not fit in visually.) |
|
For the record, I like the changes to the setting menu a lot. Also all the other recent appearance related changes are pretty decent. #93097 is a great change, too, and your addition to make the theme setting more understandable (im the same PR that removed the paint brush, I think) when not in "use system theme node" is highly logical and just makes sense. Just, I don't see any reason against also keeping the paintbrush. Properly dark themed websites are rare, properly changing browser settings can be a pain or impossible, even for experienced technical users, and even if they weren't relying on "system settings" never helps users that like theme changes on a case-by-case basis, or depending on lighting conditions or the theme of other applications they have open, nor users that share the same device and account, yet have different preferences. |
To be clear, I made that addon because I already considered themes on
It fixes the need to reload the page at the end. I guess this isn’t a big deal, but it’s one less step. |
|
@notriddle FYI, I was not intending to discredit the add-on. I understand its use for file URLs in Firefox. I don’t currently need an add-on; I’m not experiencing any problems – even on file URLs – in Google Chrome. Also, on second thought, a settings sync add-on is fairly orthogonal to this issue anyways. If I can install an add-on, I can probably also set an appropriate system theme. My main point is about new devices or other people’s devices that I might be using, or Google Chrome on Android, where I haven’t figured out a dark theme yet (and it doesn’t support extensions AFAIK), or – and that’s my main point – new or casual users of rustdoc documentation who might not know about the option to select themes in the first place. I used to be a new user myself not too long ago, on a device not configured for choosing dark themes by default, and I can say that it was easy to learn about the existence of themes in rustdoc, and easy select a different theme on a not perfectly configured device, because of the theme picker / paintbrush symbol. I’m saying that the theme picker was an important aspect of my positive experience with rustdoc when learning Rust, so I’d be quite disappointed when future learners of the language cannot make the same positive experience anymore. As I hinted at above (I think, somewhere...), the fact that Rust’s documentation had such a user-friendly approach to themes had the effect that mdbook and rustdoc really introduced me to trying out (and ultimately liking) dark-themed websites in the first place; most other websites don’t have themes, and many of the few ones that have dark themes make them insanely hard to choose manually, in particular if you haven’t re-configured your system to prefer dark themes by default. The issue I’ve opened here won’t significantly affect me personally very much. I know about themes, I can work around this, if I come across a situation where I need to change the rustdoc theme in the future, I’ll be annoyed for a second, and then dig through the settings page. I just recently watched a streamer on YouTube learning Rust for the first time, with the book. Book was in a light theme on the first stream, and a dark theme on the second. They probably discovered mdbook’s paintbrush symbol / theme picker in the meantime. I’m convinced that once they will start using standard library docs, they will easily find out about the fact that it has themes if and only if the standard library still has a theme-picker that looks (mostly) the same as the one from mdbook. I suppose the fact that many people learn Rust with the book (which is an mdbook page) is quite important here, because it means there’s great value in keeping the rustdoc theme picker similar to the mdbook theme picker. It’s even in the same position on the top, to the left of search, to the right of the side-bar there, so quite a lot of similarity. The menu elements are lower contrast though, so that seems an appropriate change that rustdoc could make here: Particularly on rustdoc’s theme “dark”, the buttons are currently white buttons on dark background. I wouldn’t mind if that changed. The mdbook buttons don’t even have an outline, I wouldn’t mind if that changed for rustdoc either for the theme-picker, help, and settings button. |
|
I also think that the painbrush being less accessible is an issue. |
|
I think the paintbrush should be brought back on the right, next to the settings icon - currently I find all these recent css changes incredibly off-putting but I think I could get used to them, but I really did like the paintbrush and the lack of it makes documentation much less usable for me |
|
Well, let's ask our UX/UI expert about this. cc @jsha My previous comment might have not been very clear about my position so just in case: I don't like not having the paintbrush as easily accessible as before but @jsha's arguments convinced me that it was too cluttered and a small cleanup was necessary. |
|
this is purely anecdotal evidence but i've noticed a lot more people in beginners channels asking how to change the documentation theme since this change was implemented - I wouldn't mind having just the settings icon instead of two, but removing the instant feedback is a major setback |
|
We've made some changes in response to the feedback here:
The process now takes just 3 clicks, all of them close to each other. Here's what it looks like now:
|
|
I'm aware of these changes. Now you're defining ayu as a light theme in that demo!? I'm not convinced anything can be as user friendly as a paintbrush icon. I'm not convinced a paintbrush symbol is a clutter or distracting or bad in any way. I am convinced that there's clear disadvantages w. r. t. discoverability and usability when NOT having it. Accessibility (which apparently is a main movation to remove the icon!?) is also greatly reduced if a user can't find the dark mode (of never learns of its existence in the first place) even though they would benefit from it. As the rust book is the main way of starting to learn the language, I still think that consistency with mdbook is a important factor. Unless mdbook removes their paintbrush, I think rustdoc should have one. I think I've had that Back functionality fail once on mobile, I don't remember the details and can't reproduce it right now. Switching between system theme enabled or disabled can leave the radio buttons in an incorrect state. Given the (unfortunate) situation that docs.rs uses nightly rustdoc and we're getting new documentation generated every day that can potentially stay being the latest version for quite a while, I'm somewhat disappointed how long the documentation keeps staying in a somewhat broken state (broken, as far as my personal perception/interpretation of the current status goes). Especially if bringing back the paintbrush icon is any realistic option (which, judging by reactions / feedback from others in this thread, I think it might be) then having it disappear and then reappear significantly later is a somewhat weird move. (If we do bring it back, by now, there'd even be the need for a beta backport potentially.) I would open a PR for this myself, just to get some more feedback whether it really should be gone and stay gone, but I'm unfortunately very unfamiliar with HTML / Javascript and such things. |
The reason these anecdotes seem unconvincing, at least to me, is that they're trying to tell me something I never disagreed with in the first place. I know that the theme switcher is harder to find than before; you don't have to convince me of that. Given that people focus more on the left-hand side of English-language web pages, and that the theme button was the leftmost option in the global toolbar, it couldn't have possibly been any easier to find before. I just don't think the theme switcher deserved to be the single most prominent button in the entire application.
Pocket actually does a better job of this than rustdoc or mdbook do, in my opinion:
It's still not as easy-to-find as rustdoc's theme switcher used to be, but the theme switcher does not deserve to be the single most prominent button in the entire application. It is still better than the dedicated Settings page, since it offers the instant feedback you want. And, most importantly, if Accessibility is your reason for offering color schemes, you really should also offer font size changes. |
Obviously with a solution of that style, I would be mostly okay. As I noted in my original post:
Comparing to status quo of the Rustdoc settings, apart from the fact that it takes you to a different page, there’s additional significant differences to the Pocket screenshot: The fact that by default there’s going to be 2 sets of selection, labelled “Preferred light theme” and “Preferred dark theme” makes this option immediately highly non-straightforward to use, and even harder to use properly (who’d guess that deselecting “Use system theme” changes the menu) (I’m considering changing the “Preferred light theme” to a dark theme to be a case of “improperly” using the settings). And there’s a label for the theme selection, but that label is very, very, very, very far removed from the selection itself. E.g. with “Use system theme” disabled, it’s ridiculous, look at the word “Theme” and what it’s supposed to be referring to:
|
So on mobile, and properly changing the option, the thing takes 4 clicks (the 4th click is deselecting “Use system theme”), and the things aren’t quite as close together and smooth:
Thinking about how to solve the problem that those “preferred … theme” options are confusing, here’s an idea Have a straightforward theme selection on top, then a toggle for system theme, and then an expandable section to customize the system theme.
Maybe different wording from “system theme”, e.g. “Choose theme automatically”
Then, in terms of interaction, if you deselect “Choose theme automatically”, the “Advanced automatic theme settings” settings disappear completely:
Similarly, if you change the theme directly at the top, then the “Choose theme automatically” setting is disabled, e.g. clicking on “◯ ayu” in the original state above, brings you directly into a state of
Finally, while
is enabled, then changing “Preferred light theme” or “Preferred dark theme” should automatically affect the current theme. I.e. the original state above
is only possible when the “system” is in dark mode (otherwise, “◉ light”, the preferred light theme, would have to be active in the first line), and clicking on “◯ ayu” under “Preferred dark theme” gets you into this state
Reenabling “Choose theme automatically” should immediately change the selected theme in the top line, too, according to the currently active preferred themes. The expandable “Customize system theme” option should, whenever it’s hidden by deselecting “Choose theme automatically”, probably remember its expansion state, so when it was expanded while it was hidden, it should re-appear expanded when you toggle “Choose theme automatically” twice. |
|
I opened #94607 and explained what we plan to do in the future. |
|
You can now select the theme in the settings menu. I think we can consider this issue as fixed then. |
It seems as if #92629 has removed the theme picker from rustdoc. Both the way to change themes as well as any indication of the fact that changing themes is possible in the first place is hidden behind a setting page that many users will probably not even use at all.
My initial experience with rustdoc and mdbook, back over 1 year ago, was quite positive because of the easy option to customize the looks / themes. I hadn't set up my browser for any dark theme yet at the point; the easy accessibility and good visibility of the paintbrush icon largely introduced me to the appeal of dark-themed documentation pages.
I have switched themes in rustdoc countless times. For every new browser, for every new device, for every new incognito window on a non-dark-theme-configured browser / device. And that number multiplied by the amount of websites that contain rustdoc, which is docs.rs, doc.rust-lang.org, and a whole lot of self-hosted pages for certain crates, like docs.serde.rs.
The change in #92629 makes changing themes about 20x more effort. Instead of 2 clicks (click paint brush, then the theme) in the same area of the page, you need to:
So over all
Previously it was
Additionally, discoverability is terrible (I estimate that – optimistically – less than half as many users will be able to find out on there own that there are themes in the first place), the settings page with its initial layout showing "preferred dark / light theme" is confusing, the need to go back to the previous page using browser navigation is confusing, and the need to refresh the page is absolutely confusing.
Finally, if I don’t know my favorite theme yet and want to compare the looks:
The change on nightly rustdoc unfortunately affects crate documentations on docs.rs immediately. In my personal opinion this change is a terrible user experience and should be reverted as fast as possible. Future attempts to remove the paintbrush icon should, in my opinion
But I don’t actually see any problem with just keeping a paintbrush symbol. Mdbook does this, too. Rustdoc pages are usually huge and full of information, I don’t see why there wouldn’t be room to keep the paintbrush symbol. I also don’t understand why a redundant way to change the same setting has to be a problem; after all, themes are a great feature, (who expects API docs to have themes? wow, Rust is so great...) and discoverability of this feature is only improved if there’s multiple ways to change them.
If you want to address the main point of #84539, well, I don’t understand how that’s a significant issue in the first place, and there are probably better solutions than removing the paintbrush symbol. For example I personally wasn’t even aware that there was a different way of choosing themes than using the paintbrush symbol. My first reaction to browsing nightly std docs was “oh no, have they now joined those websites that don’t give you any configuration option besides automagically syncing with system settings?” (These websites are terrible if you’re on a device where it’s hard to bring your browser into an actual working dark mode; this took me multiple days to achieve on my current PC (linux), and actually it’s still kind-of broken). The main question
describes a minor problem; it doesn’t really matter whether a user understands the precise logic of these settings as long as they find some option easily that makes the website look the way they want it to look. And Github is a bad comparison because it’s a central (single host) website that basically assumes you’re logged in, which immediately makes (the equivalent of) the problem of having to reconfigure for
go away. Good luck trying to change your Github theme when you’re not logged in (I’m not even sure if that’s possible at all!) Well, but for rustdoc paged, you’re never logged in! Hence, adapting Github’s approach is probably a terrible idea, isn’t it?
@rustbot label T-rustdoc
cc @jsha
The text was updated successfully, but these errors were encountered: