5 ms·

It feels unfinished. 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

It feels unfinished. 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.

thiht 2y ago
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?
- phoronixrly 2y ago
  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.
  - thiht 2y ago
    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.
  - oefrha 2y ago
    Waste time? I can make a one line change to make it basically good enough on mobile: - main { max-width: 800px; } + main { box-sizing: border-box; max-width: min(864px, 100%); } There. Anyone who thinks that's a waste of time probably shouldn't be allowed to touch the CSS of a high traffic website.
    - bollu 2y ago
      Nice! As someone who understands very little CSS, could you explain why this works?
      - thaumasiotes 2y ago
        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.
  - lolinder 2y ago
    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]). [0] https://news.ycombinator.com/item?id=41346674 https://news.ycombinator.com/item?id=41346674
  - tacker2000 2y ago
    Unimportant? Just because you dont use it on mobile doesnt mean everyone else does. Its a fact that a large share of page visits are now done on mobile, depending on the content.
- ravenstine 2y ago
  > I can’t believe a mostly text website that doesn’t scale well on mobile made it to production in this day and age. I can. This is pretty typical.
- beretguy 2y ago
  They just probably over-engineered it by using some library or framework instead of keeping it simple.
  - ameliaquining 2y ago
    This is false. You can see exactly what was changed: https://github.com/ruby/rdoc/pull/1157/files https://github.com/ruby/rdoc/pull/1157/files
lyu07282 2y ago
The text styling is nuts, light weight (400) gray (#333) for documentation, what were they thinking?
- SSLy 2y ago
  It was designed to be looked at for pleasure, not read in anger.
- mrob 2y ago
  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.
  - discreteevent 2y ago
    https://contrastrebellion.com/ https://contrastrebellion.com/
    - mrob 2y ago
      They're not serious: "color: #191919;" Here's some real high contrast, and IMO a perfectly designed website: https://motherfuckingwebsite.com/ https://motherfuckingwebsite.com/ Previous HN discussion: https://news.ycombinator.com/item?id=6791297 https://news.ycombinator.com/item?id=6791297 https://news.ycombinator.com/item?id=40956192 https://news.ycombinator.com/item?id=40956192
    - Dalewyn 2y ago
      Worth noting Hacker News is amongst the examples, and rightfully so.
  - MatthiasPortzel 2y ago
    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. => https://matthiasportzel.com 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.
phoronixrly 2y ago
> I’m not sure that the old one did either. 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.
trescenzi 2y ago
> The colour. 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.
- thiht 2y ago
  The ruby-lang website[1] uses red accents and looks gorgeous (to me at least). I wonder why they didn't just use the same colors. [1]: https://www.ruby-lang.org/fr/ https://www.ruby-lang.org/fr/
  - EasyMark 2y ago
    https://www.ruby-lang.org/en/ https://www.ruby-lang.org/en/ for the english version
- airstrike 2y ago
  Everyone knows Python is green and Ruby is red...
  - thaumasiotes 2y ago
    > Everyone knows Python is green ...why?
    - TehCorwiz 2y ago
      Sssssomething about the namesssss.
      - thaumasiotes 2y ago
        And that would be...? Pythons aren't green. It's like saying everyone knows Perl is blue, because it's represented by a camel. 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_Official.png/revision/latest?cb=20180301004815 https://static.wikia.nocookie.net/villains/images/a/a1/Kaa_O...
mekster 2y ago
Ruby site has always been red... What gives?
ameliaquining 2y ago
There seems to be active work underway to fix it on mobile: https://github.com/ruby/rdoc/pull/1162 https://github.com/ruby/rdoc/pull/1162
SkyPuncher 2y ago
I’ll be real, target mobile for language docs just doesn’t seem like a big priority. I would expect 95% of the user base to be reading these docs on a laptop or desktop.

thiht 2y ago

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?

phoronixrly 2y ago
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.
- thiht 2y ago
  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.
- oefrha 2y ago
  Waste time? I can make a one line change to make it basically good enough on mobile: - main { max-width: 800px; } + main { box-sizing: border-box; max-width: min(864px, 100%); } There. Anyone who thinks that's a waste of time probably shouldn't be allowed to touch the CSS of a high traffic website.
  - bollu 2y ago
    Nice! As someone who understands very little CSS, could you explain why this works?
    - thaumasiotes 2y ago
      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.
- lolinder 2y ago
  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]). [0] https://news.ycombinator.com/item?id=41346674 https://news.ycombinator.com/item?id=41346674
- tacker2000 2y ago
  Unimportant? Just because you dont use it on mobile doesnt mean everyone else does. Its a fact that a large share of page visits are now done on mobile, depending on the content.
ravenstine 2y ago
> I can’t believe a mostly text website that doesn’t scale well on mobile made it to production in this day and age. I can. This is pretty typical.
beretguy 2y ago
They just probably over-engineered it by using some library or framework instead of keeping it simple.
- ameliaquining 2y ago
  This is false. You can see exactly what was changed: https://github.com/ruby/rdoc/pull/1157/files https://github.com/ruby/rdoc/pull/1157/files

lyu07282 2y ago

The text styling is nuts, light weight (400) gray (#333) for documentation, what were they thinking?

SSLy 2y ago
It was designed to be looked at for pleasure, not read in anger.
mrob 2y ago
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.
- discreteevent 2y ago
  https://contrastrebellion.com/ https://contrastrebellion.com/
  - mrob 2y ago
    They're not serious: "color: #191919;" Here's some real high contrast, and IMO a perfectly designed website: https://motherfuckingwebsite.com/ https://motherfuckingwebsite.com/ Previous HN discussion: https://news.ycombinator.com/item?id=6791297 https://news.ycombinator.com/item?id=6791297 https://news.ycombinator.com/item?id=40956192 https://news.ycombinator.com/item?id=40956192
  - Dalewyn 2y ago
    Worth noting Hacker News is amongst the examples, and rightfully so.
- MatthiasPortzel 2y ago
  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. => https://matthiasportzel.com 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.

phoronixrly 2y ago

> I’m not sure that the old one did either. 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.

trescenzi 2y ago

> The colour. 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.

thiht 2y ago
The ruby-lang website[1] uses red accents and looks gorgeous (to me at least). I wonder why they didn't just use the same colors. [1]: https://www.ruby-lang.org/fr/ https://www.ruby-lang.org/fr/
- EasyMark 2y ago
  https://www.ruby-lang.org/en/ https://www.ruby-lang.org/en/ for the english version
airstrike 2y ago
Everyone knows Python is green and Ruby is red...
- thaumasiotes 2y ago
  > Everyone knows Python is green ...why?
  - TehCorwiz 2y ago
    Sssssomething about the namesssss.
    - thaumasiotes 2y ago
      And that would be...? Pythons aren't green. It's like saying everyone knows Perl is blue, because it's represented by a camel. 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_Official.png/revision/latest?cb=20180301004815 https://static.wikia.nocookie.net/villains/images/a/a1/Kaa_O...

mekster 2y ago

Ruby site has always been red... What gives?

ameliaquining 2y ago

There seems to be active work underway to fix it on mobile: https://github.com/ruby/rdoc/pull/1162 https://github.com/ruby/rdoc/pull/1162

SkyPuncher 2y ago

I’ll be real, target mobile for language docs just doesn’t seem like a big priority. I would expect 95% of the user base to be reading these docs on a laptop or desktop.