Ruby's official documentation just got a new look

Original Article ↗ Hacker News Discussion ↗

Ruby’s official documentation site has been redesigned with a new green-themed interface, drawing heavy criticism for poor readability, weak contrast, and especially broken or awkward behavior on mobile devices. Many developers find the typography and layout harder to use than the previous version, pointing to accessibility issues and confusing navigation, and several recommend alternatives such as rubyapi.org or devdocs.io instead. While a few users like the updated code blocks and note that fixes are already in progress, the overall reaction is that the visual refresh is a regression in usability and brand fit.

Overall reception

  • Many commenters dislike the redesign; a few see it as a modest improvement over a very dated look.
  • Several say it “feels unfinished” and question how it passed review, especially for mobile and accessibility.
  • Some are puzzled by the design choices but assume it was done with limited resources.

Color scheme & branding

  • The dominant green theme is widely criticized as off-brand for “Ruby,” which people strongly associate with red.
  • Some find the specific shade “vomit-like” rather than a calm or tasteful green.
  • A minority notes that the docs have actually been green for years; people may be conflating them with other Ruby/Rails sites that use red.

Typography, readability & accessibility

  • Main text is described as too light, too thin, and low-contrast, making it hard to read, especially for users with astigmatism or older eyes.
  • Overuse of bold and large amounts of whitespace make scanning harder.
  • Firefox reader mode reportedly breaks badly on the new pages.
  • Several call out accessibility regressions and poor font rendering on some platforms.

Mobile & responsiveness

  • Many report the site is borderline unusable on phones: horizontal scrolling, sidebar covering content when zoomed, and hamburger menu issues.
  • Others argue mobile docs aren’t a high priority; counterarguments insist mobile doc use is common and basic responsiveness is trivial to implement.
  • A small CSS tweak is suggested (and explained) as a near one-line fix; a linked PR shows active work to improve mobile.

Navigation, search & UX

  • Search results prioritize obscure items over core classes like File and String, a long-standing problem.
  • Some miss “next/prev” navigation between pages and complain it’s easy to get lost.
  • Cursor behavior is inconsistent (text cursor on hamburger icon, pointer in odd places).

Code blocks, performance & alternatives

  • Opinions on code blocks differ: some like the calmer, more standard syntax highlighting; others think comment contrast is now too low.
  • A few note increased CPU/rendering overhead vs. the old site.
  • Many recommend alternatives like rubyapi.org, ruby-doc.org, DevDocs, or Rails-style docs, which are seen as more modern and mobile-friendly.