- CPU usage and rendering overhead/waiting time is noticably higher than on the old version.
- The supposedly responsive functionality means that the sidebar hides ~half of main content on my default window size and resolution on desktop. I have to zoom out to be able to read at all.
I can’t believe a mostly text website that doesn’t scale well on mobile made it to production in this day and age. Was it worked on by a single person? Did no one review it and think of opening it on their mobile?
I’d even say it’s harder to make a text website NOT render well on mobile. Doesn’t HTML handle that by default, unless you use some freakishly long text without spaces?
Not every website's key metric is conversion of mobile users. I have never needed to read Ruby documentation on my phone. I'm glad they did not waste their time on unimportant stuff like mobile UX in this case.
I doubt you’re the only user of the Ruby documentation though.
I’m not a (frequent) Ruby user, but I routinely check the Go documentation, the MDN, the Python documentation, and several other language documentations on mobile. Because sometimes I will think of something while I’m walking my dog, or while I’m in my couch, or before sleeping, or at any other moment.
Mobile UX is exactly as important as desktop UX. And for a text only website (ie. not a web app) you don’t even need to spend time to make it work, it’s almost the default behavior. You have to go out of your way to make a text website that doesn’t render well on mobile.
I can't tell why it works, but I can talk about some general things I see.
First, I assume the problem is that, when viewed on mobile, this website is wider than the screen. (Or wider than the browser window.) This makes some horizontal scrolling necessary in order to read some of the text.
No matter how narrow I make the browser window on a desktop, the same problem never occurs, so at first glance this looks like a bug in the mobile browser (which for me is Firefox Focus).
The `box-sizing` CSS property determines whether you want the size of an element to be set to the value you specify, or to something else. You might ask "why would I want something else?", and that's a good question.
Anyway, `box-sizing: border-box` means that when you set the width of the element, it won't be any wider than the width that you set. The default value of this setting is `content-box`, which means that the "content" of the element won't be any wider than the width you set, but, if the element itself uses any padding or borders, those don't count toward the width and the element will be wider than you said it should be.
I assume the adjustment to `max-width` is intended to do two things:
(1) prevent the width of the element from exceeding 100%, presumably related to the width of the browser window;
(2) otherwise, raise the previous maximum by 64px, to adjust for the fact that padding is now included in the notional width of the element. There was probably 64px worth of padding originally.
The problems I see in my own analysis are:
(a) We're only adjusting the `max-width` property, which means that if an element wants to be narrower for other reasons, such as the width of the browser window, that was always allowed. It's not clear to me why this wouldn't have been happening in the page as delivered.
(b) As I mentioned above, the problem that occurs on mobile does not ever occur on desktop, no matter how narrow the browser window gets. This suggests that it isn't a problem with the CSS, but rather with the mobile browser.
I find myself reading technical docs on my phone all the time. I'm often out on a walk or shopping or whatever while thinking over a plan for a project, and when I have an idea that seems like it'd work I'll go look at the docs to make sure I'm not missing something.
They clearly wanted to support mobile (otherwise the hamburger menu is unforgivable) and already spent time making it partially work, but it looks like they just bailed out early before going the final 1% of the way to it looking polished (see a sibling's two-line fix [0]).
I blame what I'll call the Art Teacher's Fallacy: "Pure black does not exist in nature, therefore you must never use pure black." This is equivocating on the meaning of "pure black"; your paints or computer screen also exist in nature and are therefore not "pure black" in the former sense.
In print, people went to great lengths to get the highest contrast possible. I see no reason why we shouldn't do the same on screen.
I did an early project with only #ffffff, #000000, #ff0000, etc because I thought those were the most “pure” colors. It looked freaking awful.
The best colors are ones that are subtly off of pure white and pure black; to the point where you can’t even tell. My website uses #191919, which you can’t consciously tell isn’t black, but looks better for it.
Print’s a different beast. I used the same concepts to design my business cards and they looked washed out using off-black. Paper reflects environmental light (instead of emitting its own light) so you can crack the contrast as high as you want and the end result won’t be pure black on pure white.
LCDs imperfectly block the backlight to make obviously impure black for #000000. Every OLED I've seen has slight light emission for #000000 (leakage current?) too. And very few monitors are used in a perfectly dark environment, so there's light reflecting off the screen even in the #000000 areas.
Yea why the heck did they pick green? I get red can look like errors but I’m certain there’s a cheerful ruby red out there that would have worked as an accent color for Ruby’s documentation. Green just feels so wrong to me for Ruby.
I meant it more "if anyone's green, then it's Python, not Ruby". I still associate Python with green because of the typical cartoon color of snakes + Django
I had to dig into this, because I also felt Python is green.
The Python logo has been blue/yellow in the modern era and monochromatic prior, but the Python IDLE icon DID used to be green[1]. Which in practice probably cemented into my brain very early on, since I learned Python with IDLE!
It’s some kind of Mandela/Berenstain effect because the old one is also slightly green but I don’t remember Ruby’s documentation ever being green and apparently nobody else did either.
That's nice, but what I'd like is if I type the name of a major class, like "File", that the File class be on top, not some obscure method/module that contains "File" as a substring.
The search issue is also present with the docs for Ruby 3.3[1] and earlier. Incidentally, "String" is an even better example, as the the class is the fifth result returned after four other very obscure classes.
This either hasn’t been tested on a mobile device or the developer decided mobile devices weren’t important enough to properly support at launch. Bad look either way.
Accessibility-wise it has problems. Font-size, colour, contrast to name a few. And overuse of bold. When everything has emphasis, nothing does.
And green? How did that get approved?
I'm glad things are still moving in the Ruby community. I use it every day. But Elixir is winning the mind-share battle over Ruby at $dayjob these days. And their documents is second to none. One of the best that I've used.
This seems to be a reskin of the prior RDoc styles, which are visible in prior Ruby versions (e.g https://docs.ruby-lang.org/en/3.3/). Despite the rather bold green, the overall look of the primary content feels very subdued. I think a big part of it is how low-contrast the code blocks are. In the prior style, code blocks used a pretty high-contrast syntax highlighting scheme; comments were very distinct, which is important as these demonstrate return values. In the new style, it's quite difficult to distinguish comments (medium gray) from identifiers (dark gray).
Personally I prefer the look of rubyapi.org over either of the official ones, but this new one kinda feels like a step backward from the prior one.
The rails api docs are also going through a redesign, you can see a preview of the next design in edge: https://edgeapi.rubyonrails.org/classes/ActiveJob.html
I think it’s a a change in the right direction that removes the “aggressive wall of text” on longer pages and looks great in dark and light modes.
I like the new code blocks more! The syntax highlighting is more standard. I found the red comments on a grey background difficult to read in the old theme. However, I would still want to see higher contrast in the text.
It looks like the mobile view is getting fixed [1].
It is generally hard to read, even with only mild astigmatism and perfect glasses. What is even worth is that the Website does not appear to support Firefox's readability mode.
That seems to be the curse of our time: Function follows form.
I use Firefox's readability mode for quite a lot to help me process these "pretty" web pages. Most of the time it works pretty well and I can read the content even faster. Even if it doesn't work perfectly, it still provides a better contrast than the original. In the case of these new Ruby docs, it falls apart more completely than I've ever seen. It's completely unusable!
As a terrible Ruby programmer with pretty good 55 year old eyes I can't read these docs at all. Everyone is complaining about the color scheme (which I agree with) but its the font choices (lightweight, grey on grey) that kills usability for me.
When I'm looking at docs I need to find what I need quickly, and searching a sea of whitespace and barely there text is not great.
> Ruby is an interpreted object-oriented programming language often used for web development.
Talk about irony. I increased the font to 150% so I could read that very sentence, and it's literally impossible to do so, because the sidebar covers the text when you zoom in that far. And the only reason I zoomed in that far was because they used Lato-light rather than Lato-regular. Maybe Ruby isn't used for accessible web development.
> Maybe Ruby isn't used for accessible web development.
What an unnecessary comment. Sure, the docs website could use more work, but what does the choice of a language used for back-end development have to do with the quality of the front-end code (non-Ruby) in those same projects?
It's 2024. Accessibility is absolutely worthy of comment, particularly if you're boasting about being a language used for web development. They could have used one of the thousands of available existing solutions rather than rolling their own.
> a language used for back-end development have to do with the quality of the front-end code (non-Ruby)
Ruby is used for a more than the back-end. Check out Sinatra or Rails.
If I change the color hue of all the CSS variables from green to red, and make the text a bit darker and larger it's not so bad. With a light gray background on the sidebar to provide some contrast with the main content like the Rust doc does I quite like it.
I'll probably create custom CSS rules for the doc if this is the final version and be happy with it. I've been using a custom dark theme for HN for years and I'm happy with it. I'm glad we still have enough control over web pages to do that!
What we really need is a common downloadable documentation format so that we can more easily build tools to read documentation of all languages and libraries in one place with unified interface, instead of jumping between tens of browser tabs each with a different (new) look.
I know there is devdocs [1], but unfortunately it need to implement scrapers and filters for each site specifically.
108 comments
[ 2.5 ms ] story [ 186 ms ] threadAnd why the hell green? Ruby's not Python :(
You mean Ruby's not Emerald ;)
Has anyone tried rendering the current docs with the old theme?
- CPU usage and rendering overhead/waiting time is noticably higher than on the old version.
- The supposedly responsive functionality means that the sidebar hides ~half of main content on my default window size and resolution on desktop. I have to zoom out to be able to read at all.
It doesn’t work very well on mobile. Though, I’m not sure that the old one did either.
There’s too much white space. Documentation should be compact so that you can fit as much as possible on the screen while remaining legible.
The colour.
I’d even say it’s harder to make a text website NOT render well on mobile. Doesn’t HTML handle that by default, unless you use some freakishly long text without spaces?
I’m not a (frequent) Ruby user, but I routinely check the Go documentation, the MDN, the Python documentation, and several other language documentations on mobile. Because sometimes I will think of something while I’m walking my dog, or while I’m in my couch, or before sleeping, or at any other moment.
Mobile UX is exactly as important as desktop UX. And for a text only website (ie. not a web app) you don’t even need to spend time to make it work, it’s almost the default behavior. You have to go out of your way to make a text website that doesn’t render well on mobile.
First, I assume the problem is that, when viewed on mobile, this website is wider than the screen. (Or wider than the browser window.) This makes some horizontal scrolling necessary in order to read some of the text.
No matter how narrow I make the browser window on a desktop, the same problem never occurs, so at first glance this looks like a bug in the mobile browser (which for me is Firefox Focus).
The `box-sizing` CSS property determines whether you want the size of an element to be set to the value you specify, or to something else. You might ask "why would I want something else?", and that's a good question.
Anyway, `box-sizing: border-box` means that when you set the width of the element, it won't be any wider than the width that you set. The default value of this setting is `content-box`, which means that the "content" of the element won't be any wider than the width you set, but, if the element itself uses any padding or borders, those don't count toward the width and the element will be wider than you said it should be.
I assume the adjustment to `max-width` is intended to do two things:
(1) prevent the width of the element from exceeding 100%, presumably related to the width of the browser window;
(2) otherwise, raise the previous maximum by 64px, to adjust for the fact that padding is now included in the notional width of the element. There was probably 64px worth of padding originally.
The problems I see in my own analysis are:
(a) We're only adjusting the `max-width` property, which means that if an element wants to be narrower for other reasons, such as the width of the browser window, that was always allowed. It's not clear to me why this wouldn't have been happening in the page as delivered.
(b) As I mentioned above, the problem that occurs on mobile does not ever occur on desktop, no matter how narrow the browser window gets. This suggests that it isn't a problem with the CSS, but rather with the mobile browser.
They clearly wanted to support mobile (otherwise the hamburger menu is unforgivable) and already spent time making it partially work, but it looks like they just bailed out early before going the final 1% of the way to it looking polished (see a sibling's two-line fix [0]).
[0] https://news.ycombinator.com/item?id=41346674
Its a fact that a large share of page visits are now done on mobile, depending on the content.
I can. This is pretty typical.
In print, people went to great lengths to get the highest contrast possible. I see no reason why we shouldn't do the same on screen.
"color: #191919;"
Here's some real high contrast, and IMO a perfectly designed website:
https://motherfuckingwebsite.com/
Previous HN discussion:
https://news.ycombinator.com/item?id=6791297
https://news.ycombinator.com/item?id=40956192
The best colors are ones that are subtly off of pure white and pure black; to the point where you can’t even tell. My website uses #191919, which you can’t consciously tell isn’t black, but looks better for it.
=> https://matthiasportzel.com
Print’s a different beast. I used the same concepts to design my business cards and they looked washed out using off-black. Paper reflects environmental light (instead of emitting its own light) so you can crack the contrast as high as you want and the end result won’t be pure black on pure white.
You probably don't remember because you have not needed to read Ruby documentation on mobile. Good news though -- I suspect you are not alone in this.
Yea why the heck did they pick green? I get red can look like errors but I’m certain there’s a cheerful ruby red out there that would have worked as an accent color for Ruby’s documentation. Green just feels so wrong to me for Ruby.
[1]: https://www.ruby-lang.org/fr/
...why?
Here's the least reality-informed, most popularly well-known image of a python you can find: https://static.wikia.nocookie.net/villains/images/a/a1/Kaa_O...
The Python logo has been blue/yellow in the modern era and monochromatic prior, but the Python IDLE icon DID used to be green[1]. Which in practice probably cemented into my brain very early on, since I learned Python with IDLE!
[1]: https://github.com/certik/python-2.7/blob/master/Lib/idlelib...
The goal was to move in the right direction, but make it similar enough that it would get quick approval without rocking the boat much (yet).
I would expect 95% of the user base to be reading these docs on a laptop or desktop.
- Its very hard to navigate around and easy to get lost with links.
- Mobile view is borderline unusable. Need to scroll horizontally to read a sentence.
- Cursor is a beam while hovering over the sandwich menu icon
[1]: https://docs.ruby-lang.org/en/3.3/
And green? How did that get approved?
I'm glad things are still moving in the Ruby community. I use it every day. But Elixir is winning the mind-share battle over Ruby at $dayjob these days. And their documents is second to none. One of the best that I've used.
Personally I prefer the look of rubyapi.org over either of the official ones, but this new one kinda feels like a step backward from the prior one.
- sent from my iPhone
That one's a bit too much red for my taste :) There's a sweet spot to find that's closer to "nice accent colors" than "aggressive red wall of text"
It looks like the mobile view is getting fixed [1].
[1] https://github.com/ruby/rdoc/pull/1162
That seems to be the curse of our time: Function follows form.
As a terrible Ruby programmer with pretty good 55 year old eyes I can't read these docs at all. Everyone is complaining about the color scheme (which I agree with) but its the font choices (lightweight, grey on grey) that kills usability for me.
When I'm looking at docs I need to find what I need quickly, and searching a sea of whitespace and barely there text is not great.
Hilarious!
Random example: https://docs.ruby-lang.org/en/master/ARGF.html#method-i-each
Love the new colour scheme, easy to read (on desktop) and feels more chill than reds and greys.
The main font is very thin light gray font to begin with that makes it very hard to read even on a 4k monitor
Talk about irony. I increased the font to 150% so I could read that very sentence, and it's literally impossible to do so, because the sidebar covers the text when you zoom in that far. And the only reason I zoomed in that far was because they used Lato-light rather than Lato-regular. Maybe Ruby isn't used for accessible web development.
What an unnecessary comment. Sure, the docs website could use more work, but what does the choice of a language used for back-end development have to do with the quality of the front-end code (non-Ruby) in those same projects?
It's 2024. Accessibility is absolutely worthy of comment, particularly if you're boasting about being a language used for web development. They could have used one of the thousands of available existing solutions rather than rolling their own.
> a language used for back-end development have to do with the quality of the front-end code (non-Ruby)
Ruby is used for a more than the back-end. Check out Sinatra or Rails.
I'll probably create custom CSS rules for the doc if this is the final version and be happy with it. I've been using a custom dark theme for HN for years and I'm happy with it. I'm glad we still have enough control over web pages to do that!
I know there is devdocs [1], but unfortunately it need to implement scrapers and filters for each site specifically.
[1] https://devdocs.io/