Ruby's official documentation just got a new look

https://docs.ruby-lang.org/en/master/

by thunderbong • 2 years ago

149 104 2 years ago

docs.ruby-lang.org

strzibny• 2 years ago

Oh no, much prefered the old look.

And why the hell green? Ruby's not Python :(

pyinstallwoes• 2 years ago

Yeah that’s weird

yumraj• 2 years ago

Ruby's not Python :(

You mean Ruby's not Emerald ;)

pentestercrab• 2 years ago

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• 2 years ago

Big nope.

3np• 2 years ago

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.

zarzavat2• 2 years ago

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.

thiht5• 2 years 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?

phoronixrly2• 2 years 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.

ravenstine• 2 years 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• 2 years ago

They just probably over-engineered it by using some library or framework instead of keeping it simple.

lyu07282• 2 years ago

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

SSLy• 2 years ago

It was designed to be looked at for pleasure, not read in anger.

mrob3• 2 years 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.

phoronixrly2• 2 years 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.

trescenzi2• 2 years 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.

thiht5• 2 years 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/

airstrike3• 2 years ago

Everyone knows Python is green and Ruby is red...

zarzavat2• 2 years ago

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.

trueismywork• 2 years ago

Green calms me down. As someone who gets extremely angry at the Ruby code I have to maintain, green is good.

amomchilov• 2 years ago

It's a temporary and incremental improvement over the previous stylesheet, which was also green (for reasons still unknown): https://docs.ruby-lang.org/en/3.3/String.html

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).

mekster• 2 years ago

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

ameliaquining3• 2 years ago

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

SkyPuncher• 2 years 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.

porgarmer• 2 years ago

- 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_trough2• 2 years ago

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.

ilikepi2• 2 years ago

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_trough2• 2 years ago

I'd love to know where that ordering comes from. Insanity!

retrac98• 2 years ago

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• 2 years ago

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• 2 years ago

The main font color for Ruby is... green?

ilikepi2• 2 years ago

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• 2 years ago

Doesn’t work on mobile

- sent from my iPhone

wiseowise• 2 years ago

Not optimized for mobile in 2024, seriously?

marginalia_nu• 2 years ago

Given how technical documentation is typically used, when would you view it on a mobile device?

orhmeh09• 2 years ago

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• 2 years ago

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.

thiht5• 2 years ago

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• 2 years ago

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.

felipemesquita• 2 years ago

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.

tapanih• 2 years ago

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• 2 years ago

Sadly, the typography looks too neglected for the time when there is such an abundance of templates and fonts.

lawgimenez• 2 years ago

The font is not good for my bad eyesight with severe astigmatism.

Archelaos• 2 years ago

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• 2 years ago

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• 2 years ago

It's called Ruby, but the color theme is green.

Hilarious!

Themainfn• 2 years ago

the font looks stuck at 99%

nomilk• 2 years ago

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.

pilaf2• 2 years ago

Would be nice if the hidden by default C code was syntax-highlighted as well.

troupo• 2 years ago

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

bachmeier2• 2 years ago

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.

pilaf2• 2 years ago

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?

bachmeier2• 2 years ago

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• 2 years ago

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• 2 years ago

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• 2 years ago

I remember this kind of UX being prevalent in the early 2010s or so. Fortunately most docs have moved on.

Taig• 2 years ago

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.

thiht5• 2 years ago

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• 2 years ago

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• 2 years ago

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• 2 years ago

I've been using devdocs.io for ruby and rails api docs.

pawelduda• 2 years ago

Don't like it, don't know what problems it was supposed to solve

nilslindemann• 2 years ago

* Ugly font rendering * Underscores in page names * No 'next' and 'prev' buttons.

When that is done it should be a good start.

rob• 2 years ago

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• 2 years ago

Yeah, odd choice of colors.

matteason• 2 years ago

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• 2 years ago

No dark mode? Seriously?

InMice• 2 years ago

Darkreader plugin to the rescue

elif• 2 years ago

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• 2 years ago

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• 2 years ago

Here’s the PR. I don’t know whether it was discussed elsewhere. https://github.com/ruby/rdoc/pull/1157

alabhyajindal• 2 years ago

Looks terrible. Very sad.

cute_boi• 2 years ago

They should probably get idea from Laravel docs.

usernamed7• 2 years ago

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• 2 years ago

Not the best redesign, but probably the most upvotes and comments on a Ruby related post lately, so yay?

yunwal2• 2 years ago

Up there with Tropicana and Gap for senseless rebrands

ameliaquining3• 2 years ago

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• 2 years ago

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• 2 years ago

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• 2 years ago

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.

Ruby's official documentation just got a new look

Related Stories