Ask HN: Why is Ruby so poorly documented? | Hacker News Reader

Ask HN: Why is Ruby so poorly documented?

32 pointsznpy22 comments

I need to pick up ruby for work, and headed to ruby-lang.org.

I've mostly worked with Python so far, and my best companions have been the Python tutorial (https://docs.python.org/3/tutorial/index.html), the library reference (https://docs.python.org/3/library/index.html) and the language reference (https://docs.python.org/3/reference/index.html).

I was very surprised to see that on ruby-lang.org there is practically no equivalent o the Python tutorial. The closest thing is the on-line version of the pickaxe book (https://ruby-doc.com/docs/ProgrammingRuby/) which is about Ruby 1.6, released in September 2000.

There are a myriad of other small or smaller resources (koans and stuff) but no just-sit-down-and-read-all-this document.

So the question is... Why is ruby so poorly documented? How is one supposed to learn ruby nowadays, properly ?

View on HN

The "documentation" page lists 6 different "getting started" guides. https://www.ruby-lang.org/en/documentation/

It also links to https://try.ruby-lang.org/ which has a series of quick tutorials to go through learning Ruby in the browser, without having to install anything on your computer.

I don't think "poorly documented" is a fair description of those resources.

Not 6, 9. There are three more at the top of the side bar at the right.

The most prominent one is the FAQ, though. I don’t think that’s the best starting point.

One could also argue that giving people so much choice isn’t the best idea.

Yup, six or nine different documents possibly repeating the same basic stuff but no single document teaching the language from start to finish

There’s a brand new Pickaxe for 3.2: https://pragprog.com/titles/ruby5/programming-ruby-3-2-5th-e...

I learned from it for 1.7 ages ago, and I’d still recommend it (especially since it’s been updated).

Ruby is far from being poorly documented. It just isn't documented in the way you are typically used to, coming from Python.

There are quite few initiatives that tried to do what the Python tutorial, but ultimately failed or didn't get enough traction in the Ruby land.

The best method in my opinion to learn Ruby is to just try to code a Rails app and learn along the way, but if you like to stop and read and learn the language constructs, the Pickaxe book is the best. It isn't stuck in 1.6 as you've mentioned, it was just released for Ruby 3.2.

There are so many other Ruby books as well, like eloquent Ruby and so on.

Another solution is do a course on pluralsight or any other website, I bet there are many teachers and tutors that will help you nail down the language's basics.

BTW, just showcasing how the Ruby community can document well... the Rails documentation is the best documentation I've ever read. It's concise and presents basically every concept of the framework with practical examples.

I'd say Rust and Elixir have also good documentation, but I've never came across with a so well thought out doc as the Rails one.

What do you mean with "It just isn't documented in the way you are typically used to, coming from Python"? Is the difference that it's documented in various "unofficial" places rather than in a single official site like in Python?

I've had the same experience as the OP and still haven't figured out where to find proper Ruby documentation.

https://ruby-doc.org is one place to access the documentation.

In the dawn of Ruby, the pragmatic programmers guide to ruby was how I got started. It’s free online now :

http://ruby-doc.com/docs/ProgrammingRuby/

«This book documents Version 1.6 of Ruby, which was released in September 2000.»

To be fair for learning Ruby it doesn't matter. If he wants to learn modern Ruby he could just cold start in the tutorial section. If he wants to learn why ruby is ruby the age really doesn't matter.

A couple of quick Ruby resources for python folk.

To Ruby From Python https://www.ruby-lang.org/en/documentation/ruby-from-other-l...

Ruby tutorial for Python programmers: How to make the switch https://www.educative.io/blog/ruby-tutorial-python-programme...

I discovered ruby in 2004 and fell in love with it.

tell me your current programming skills and then I can suggest you to build something meaningful and learn the language features along with it.

text file processing connecting to database and generate reports processing emails build a static site generator build a simple website with sinatra build a large app with ruby on rails

my twitter id is same as HN id, I can share more pointers, good code to read to master your skills

From my experience there are 2 ways people got into Ruby.

1. By learning Ruby

Don't mind how old the guide is. Ruby is still Ruby, sure plenty of things are better now but the old syntax is still supported and used. I don't see an issue with learning from poignants guide today as I did back then.

You should be able to run 99% of all tutorial examples without modifications in a modern ruby interpreter.

2. Headstarting into Rails

Just start building CRUD apps after any recent tutorial. Video or text whatever you prefer. Ruby is shining trough and after some time you'll learn what's Ruby, what's Rails and what is just you.

This looks like Ruby's equivalent to the Python docs:

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

There are people who are great at coding. There are people who are great at documentation. They are not always the same. Working with open source software - I find the ones who work on documentation tend to not be adding the code.

I have to agree with this. An also, Rails.

There are some API methods very poorly documented and all you can do is try to get lucky for a 2007-2009 comment in it.

One big issue is that Google highly prefers outdated documentation pages. It's usually worth to check which version you landed on.

I remember trying to learn Ruby on Rails. I read all the books and started playing around with scaffolding. It was giving me problems and I was talking to a senior developer from the community about it and he said: “Everyone knows you don’t use scaffolding, no one does that.”

It was super confusing because ALL of the documentation EVERYWHERE said to do it that way, but in the community of pro developers, they all knew it was just a stunt feature to make it easy to onboard.

I think perhaps it is rooted in the nature of how Ruby was created, more of a an amorphous mob of hobbyist hipster pot smoking ultra laid back creative engineers who dropped out of high school versus “.NET” or Java which are backed by major enterprises.

All scaffolding does is sets up a controller and views with some basic forms, and generates a model and migration like you would’ve generated anyway. It’s not like there’s anything unique or difficult to refactor about the ~6 files it generates, it’s just a basic CRUD entity to start building from. (Which , if you’re building a rails app, is probably going to involve lots of CRUD forms)

Anyone telling you that’s bad is doing a tiny bit more work than they need to!

As someone that enjoys a fair amount of pot, I’m ultra-laid-back enough to favour letting the machine do a tiny bit more of the work.

laziness is a virtue.

One can customize the scaffolding generators to output layouts/pages in the designs which one prefers. This supercharges your development especially if most of the work is CRUD like apps. https://github.com/rails/rails/tree/main/railties/lib/rails/...

I've worked with a rails core developer while I learned rails and while he likely never used scaffolding (he might had a Emacs routine setup doing more or less the same) it was definitely ok to use scaffolding.

I am lazy I still use scaffold these days, but then I also take 5 minutes to reiterate over the created files to get them the way I want them.

Reply on news.ycombinator.com