[HN Gopher] Ruby's official documentation just got a new look
___________________________________________________________________
Ruby's official documentation just got a new look
Author : thunderbong
Score : 122 points
Date : 2024-08-25 03:01 UTC (20 hours ago)
(HTM) web link (docs.ruby-lang.org)
(TXT) w3m dump (docs.ruby-lang.org)
| strzibny wrote:
| Oh no, much prefered the old look.
|
| And why the hell green? Ruby's not Python :(
| pyinstallwoes wrote:
| Yeah that's weird
| yumraj wrote:
| > Ruby's not Python :(
|
| You mean Ruby's not Emerald ;)
| pentestercrab wrote:
| I have to agree with you. It is a shame the classic style isn't
| available at an alternate subdomain or directory.
|
| Has anyone tried rendering the current docs with the old theme?
| stevenfoster wrote:
| Big nope.
| 3np wrote:
| Two regressions I noted right away (chromium):
|
| - 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.
| zarzavat wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| Nice! As someone who understands very little CSS, could
| you explain why this works?
| thaumasiotes wrote:
| 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 wrote:
| 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
| ravenstine wrote:
| > 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 wrote:
| They just probably over-engineered it by using some library
| or framework instead of keeping it simple.
| ameliaquining wrote:
| This is false. You can see exactly what was changed:
| https://github.com/ruby/rdoc/pull/1157/files
| lyu07282 wrote:
| The text styling is nuts, light weight (400) gray (#333) for
| documentation, what were they thinking?
| SSLy wrote:
| It was designed to be looked at for pleasure, not read in
| anger.
| mrob wrote:
| 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 wrote:
| https://contrastrebellion.com/
| mrob wrote:
| They're not serious:
|
| "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
| Dalewyn wrote:
| Worth noting Hacker News is amongst the examples, and
| rightfully so.
| MatthiasPortzel wrote:
| 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
|
| 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.
| mrob wrote:
| 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.
| phoronixrly wrote:
| > 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 wrote:
| > 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 wrote:
| 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/
| EasyMark wrote:
| https://www.ruby-lang.org/en/ for the english version
| airstrike wrote:
| Everyone knows Python is green and Ruby is red...
| thaumasiotes wrote:
| > Everyone knows Python is green
|
| ...why?
| TehCorwiz wrote:
| Sssssomething about the namesssss.
| thaumasiotes wrote:
| 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.wiki
| a.nocookie.net/villains/images/a/a1/Kaa_O...
| airstrike wrote:
| Ask a kid to draw a snake and which colored pencil will
| they reach out to 9 out of 10 times? Or just look at the
| snake emoji...
| EasyMark wrote:
| https://nationalzoo.si.edu/animals/green-tree-python
| yunwal wrote:
| Python has always been blue and yellow
| airstrike wrote:
| 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
| i80and wrote:
| 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!
|
| [1]: https://github.com/certik/python-2.7/blob/master/Lib
| /idlelib...
| trescenzi wrote:
| Wow I haven't seen that logo in so long. Love it, thanks
| for the reminder.
| dchest wrote:
| Python 2 docs used to be greenish
| https://docs.python.org/2.7/tutorial/modules.html#intra-
| pack...
| zarzavat wrote:
| 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.
| mekster wrote:
| Ruby site has always been red... What gives?
| ameliaquining wrote:
| There seems to be active work underway to fix it on mobile:
| https://github.com/ruby/rdoc/pull/1162
| porgarmer wrote:
| - Why is this dark green?
|
| - 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
| baggy_trough wrote:
| 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.
| ilikepi wrote:
| 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.
|
| [1]: https://docs.ruby-lang.org/en/3.3/
| baggy_trough wrote:
| I'd love to know where that ordering comes from. Insanity!
| retrac98 wrote:
| 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.
| jspash wrote:
| 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.
| dudeinjapan wrote:
| The main font color for Ruby is... green?
| ilikepi wrote:
| 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.
| rootedbox wrote:
| Doesn't work on mobile
|
| - sent from my iPhone
| wiseowise wrote:
| Not optimized for mobile in 2024, seriously?
| marginalia_nu wrote:
| Given how technical documentation is typically used, when would
| you view it on a mobile device?
| orhmeh09 wrote:
| Extremely often. I look at source code, API docs, issues,
| etc. on my phone all the time when I am on the bus or in the
| bathroom or in bed or wherever.
| jimworm wrote:
| I wouldn't mind if ruby copied the rails docs style exactly
| (https://api.rubyonrails.org/), and I'm pretty sure rails
| wouldn't mind either.
| thiht wrote:
| https://api.rubyonrails.org/classes/ActiveJob.html
|
| 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"
| james_marks wrote:
| The challenge is that if you only sprinkle some red in for
| accents, the accents look even more like an error. It's a
| conundrum.
| tapanih wrote:
| 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].
|
| [1] https://github.com/ruby/rdoc/pull/1162
| biql wrote:
| Sadly, the typography looks too neglected for the time when there
| is such an abundance of templates and fonts.
| lawgimenez wrote:
| The font is not good for my bad eyesight with severe astigmatism.
| Archelaos wrote:
| 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.
| Corrado wrote:
| 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.
| aa_is_op wrote:
| It's called Ruby, but the color theme is green.
|
| Hilarious!
| Themainfn wrote:
| the font looks stuck at 99%
| nomilk wrote:
| Lots of (justified) negative observations. But I love the way the
| code looks (which, by far, is the most important thing for
| documentation of code).
|
| 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.
| pilaf wrote:
| Would be nice if the hidden by default C code was syntax-
| highlighted as well.
| troupo wrote:
| > 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
| bachmeier wrote:
| > 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.
| pilaf wrote:
| > 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?
| bachmeier wrote:
| > What an unnecessary comment.
|
| 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.
| vinc wrote:
| 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!
| blahgeek wrote:
| 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.
|
| [1] https://devdocs.io/
| mkl95 wrote:
| I remember this kind of UX being prevalent in the early 2010s or
| so. Fortunately most docs have moved on.
| Taig wrote:
| There is a lot wrong here. But my favorite messed up detail is
| how my cursor changes to text mode when I hover the hamburger
| button on the top left.
| thiht wrote:
| The cursor also switches to "pointer" (the hand) for no reason
| on the documentation pages, eg. here: https://docs.ruby-
| lang.org/en/master/String.html#method-i-ri...
| Alifatisk wrote:
| So what alternatives is there to the official docs?
|
| ruby-docs.org is sadly gone
| https://web.archive.org/web/20230615061406/https://www.ruby-...
|
| There is https://rubyapi.org and https://ruby-doc.org left from
| what I know
| ljm wrote:
| Anything except ApiDock which always seems to take precedence
| in Google over the official documentation (albeit for Rails)
| and is almost never what you're looking for.
| derencius wrote:
| I've been using devdocs.io for ruby and rails api docs.
| pawelduda wrote:
| Don't like it, don't know what problems it was supposed to solve
| nilslindemann wrote:
| * Ugly font rendering * Underscores in page names * No 'next' and
| 'prev' buttons.
|
| When that is done it should be a good start.
| rob wrote:
| Nothing like making green the primary color on your "Ruby"
| website and spending zero minutes checking it on mobile to notice
| that every page horizontally scrolls.
| johnisgood wrote:
| Yeah, odd choice of colors.
| matteason wrote:
| Is the font rendering any better on other platforms? On Windows
| it's so poorly hinted that the top and bottom of the lowercase
| 's' are disconnected
| jacamera wrote:
| No dark mode? Seriously?
| InMice wrote:
| Darkreader plugin to the rescue
| elif wrote:
| This reminds me of all the times a manager asked if I (backend
| dev) could 'just do a little interface for xyz'
|
| Like what do you expect from me? I would be rendering these docs
| in a w3 emacs frame...
| jeremymcanally wrote:
| There are a lot of odd choices here. Is there a mailing list
| thread or something where this was worked out? I couldn't seem to
| find one on a quick scan, but I don't know where these
| discussions happen these days.
|
| I really don't want to assume incompetence or ignorance at all
| since I'm sure someone worked really hard on this. But I'm
| genuinely puzzled by a lot of what's going on.
| tomstuart wrote:
| Here's the PR. I don't know whether it was discussed elsewhere.
| https://github.com/ruby/rdoc/pull/1157
| alabhyajindal wrote:
| Looks terrible. Very sad.
| cute_boi wrote:
| They should probably get idea from Laravel docs.
| usernamed7 wrote:
| Why is it green? It shouldn't be green. Ruby docs should be red.
|
| If i stumbled onto this site while looking for docs about a ruby
| method, i'd think I landed on the docs for some other programming
| language or fork of ruby. That's how off-brand this is - to the
| point of being disorienting as a user.
|
| There are not a lot of things that create a brand around a
| programming language, and color is definitely one of them.
|
| This is such a tasteless design decision for something meant to
| be official ruby documentation that I can't even appreciate any
| other changes that docs may introduce. And then the fact that it
| doesn't even work on mobile...
|
| I am truly baffled anyone would think this is in good taste.
|
| the last time I saw such a fumble with ruby related docs was back
| around 2014 when relishapp was the only place to get rspec docs.
| It's UX was such a painful mess that i just avoided it at all
| costs. Glad to see it's dead now.
| pmdr wrote:
| Not the best redesign, but probably the most upvotes and comments
| on a Ruby related post lately, so yay?
| yunwal wrote:
| Up there with Tropicana and Gap for senseless rebrands
| ameliaquining wrote:
| To everyone commenting about it being green: This isn't a new
| change, it's always been like that.
| https://web.archive.org/web/20141203122328/http://docs.ruby-...
|
| If you thought it used to be red, you are probably thinking
| either of ruby-doc.org, which is an unofficial third-party site
| (but is older than docs.ruby-lang.org), or of the Rails docs.
| flufluflufluffy wrote:
| The vomit-green color is my favorite part. Like, they didn't even
| try for a forest-green, or lime-green, nope. went straight for
| vomit
| majewsky wrote:
| Here's a user stylesheet to make it slightly more readable:
| #root { color: black; } main { color: var(--text-color); }
|
| Regular reminder to all designers that not everyone uses an Apple
| 50K Retina Ultra Whatever Display in a professionally lit studio
| apartment.
| oglop wrote:
| People not in the Ruby unity probably don't realize Ruby takes a
| very liberal approach to its docs.
|
| Most people just use rubyapi.org because it's modern and looks
| good. It's backed by the Ruby foundation.
|
| These docs are just the "official docs" which I almost never even
| use anyways. Glad they don't look like they're from 2001 anymore
| but I'm likely to keep using rubyapi.org as it's just way out
| ahead in looks and mobile support.
___________________________________________________________________
(page generated 2024-08-25 23:02 UTC)