I spent all my time trying to figure out ‘how to do things’. Once I figured it out, it was great…and elegant…but what’s the point, there was too much magic at times to figure out what was happening.

A language can be pretty, but it’s the libraries that make it useful and practical.

I learned an important lesson: judge technology by documentation, not by the fact it is sexy or elegant.

However, the API is not the language. Not at all. You don’t have to use any of those 108 libraries to use Ruby.

If you understand network programming, the constants in the socket library should be self-evident. See where I am going here?

Here’s what I discovered this weekend
- In the standard library, in IO/wait. From what I’m able to tell, the first method,”nread”, doesn’t even exist for the Windows implementation of the interpreter. I can see the other methods from that class, but this one literally is not there. No mention of this in the API.

- The second method, “ready”, does exist but is WRONGLY implemented — I dont even think its a bug. It ALWAYS returns false, no matter what, like the implementer just got lazy. I just can’t understand that…either implement it, or at least put a note in the API, or at least throw an error when its called that says “WARNING: not implemented on your OS!”. Took me hours to figure this out. Tell me, Matz, how exactly does this fit in with the Principle of Least Surprise?

- The doc for the primary IO class has no references to IO/wait or Open3, both of which are also part of the standard library and are essentially extensions of the primary IO class which are very valuable.

- The doc for IO.select just contains a link to the doc for Kernel.select. The doc for Kernel.select just contains a link to the doc for Kernel.select. That’s right, it has a link to itself, lmao.

- All links in the API seem to be done somewhat mechanically, rather than being done by humans. So the definition for IO.read_nonblock says it works by “using the read(2) system call”. The “read” part of read(2) is a link to IO.read, which is a blocking read that takes N bytes. So if you interpret the documentation literally, it defines IO.read_nonblock as a blocking read of 2 bytes. If you’re someone who happens to know UNIX system calls, you might recognize the typo. But this kind of bullshit is rampant throughout the documentation, and I feel bad for the confused kid who’s trying to pick up his first programming language, ruby, and is completely lost.

And if I want to edit the docs myself, the only thing I can find is this BS about how I have to access their subversion repository and modify the source code. To fix a typo? A simple “corrections” submission form would be too difficult because…?

I’m only angry because I genuinely LIKE the language. The OO features, the basic data structures, even little things like ruby’s equivalent of a Switch statement are very expressive, well-abstracted, and beautiful. But once I start dealing with anything system-related I feel like I’m using poorly-documented C functions. The language is bloody 15 years old and they still can’t be bothered to make it accessible. Or maybe its just my fault and I’m the idiot for not learning Japanese!

>_<
Waaaaaaaaaaaaaaaaaaa

I have plans in the works to create a development site on which I’ll be posting a bunch of programming tips and tricks that I’ve learned over the many years I’ve been programming. More specifically, I’ll probably personally focus on Rails due to the lack of good documentation, but there’s certainly room for others to help with other languages.

I started by getting an overview of the language itself, which I quite like. I then moved on to looking how I would implement things that I have already implemented in PHP. Take, for example, symmetric encryption. There’s apparantly an MCrypt library, and an OpenSSL library for Ruby, but the documentation is astoundingly bad. After half an hour of searching, I could only find a few examples. The ruby-doc.org section on OpenSSL is pretty much empty. Compare this with the PHP documentation, and the difference is obvious.

As much as I would like to learn and use Ruby, it won’t speed up my development if I can’t access decent documentation.

I really enjoy Java docs, the description is so well put together. Why wouldn’t everybody follow that standard?!

… Yes, I was being sarcastic. Sad to hear Ruby has such poor documentation, I was motivated to learn it soon. If you find the time, contribute to it yourself, so the next guy doesn’t need to find some obscure IBM paper.