Ruby Documentation Sucks

Okay, this is going up a day late. My bad. I’ve been busy. Regardless, I have a rant which any programmer can sympathize with.

I’ve been recently programming a proxy in the Ruby programming language, which is known for its code elegance. When you know how to use it, it’s a great language. The problem, however, comes when to learning about the API in the language. To put it bluntly, the documentation is crap. To be more specific, a good amount of it is incomplete, and those sections that are completed fail to follow a consistent fashion. To put things in perspective, there are 108 core libraries included in the Ruby documentation; over half of those libraries have incomplete documentation.

Now, this isn’t that much of an issue if you know how to use the language; after all, there’s no need to go to the documentation when you know the language. The problem comes when you are like me, learning how to use the language, and don’t know what any of the constants for the sockets library do, which is a bit of a problem when you need to program a proxy. See where I’m going with this?

Maybe I’m complaining because I’ve been spoiled on PHP‘s phenomenal documentation, which is an amazing feat when it comes to documentation. All of the functions are properly laid out with plenty of cross-references, and tell you exactly what to expect for each and every function. The documentation is a work of art, I kid you not. Don’t believe me? Try learning how to do something complex in PHP using the documentation only, then try to do the same in Ruby.

I have heard some people make the argument that Ruby is open source and relies on its members to do the documentation, hence the lack of it. While I understand this argument, it doesn’t entirely make sense. Ruby has a large band of dedicated followers (think Jehovah’s Witnesses-style) who should have filled in the 1.9 documentation by now. Thinking about it from another perspective, PHP is a free and open source language as well, and look at the detail in there compared to Ruby.

All I’m saying is that Ruby needs to step up its game a bit, otherwise it will have trouble competing for those people looking at learning a new language. If it wasn’t for an amazing IBM document on Ruby socket programming, I would have moved on to another language by now.

Anyways, tune in this Friday for something different. I realize programming isn’t everybody’s cup of tea, so I’m hoping to branch off into something a little different for those of you who either find computers boring, or those of you that simply don’t understand them. As always, I appreciate you reading, and I appreciate even more those of you who tell a friend about my blog :).

Going Open Source

The first time I wrote a full website, I made a lot of mistakes. A LOT.

Although not completely obvious from looking at it on the outside, H2H Security Group is built on a pretty shoddy content management system (CMS). There are bugs, there are incomplete sections of the site, and there is little administration that doesn’t require direct database access. I’ve stopped development on the current CMS and decided to go for a complete overhaul. That’s right: I’m completely re-building the system, H2H CMS, from the ground up.

Normally, this would be a preposterous idea, and perhaps it’s not the most efficient route for me to take, but I won’t be walking away from the CMS empty handed. It was an amazing experience working on it. Despite it being terribly designed, I’ve grown a lot as a programmer since I first started. I’ve learned about things like classes, hierarchies, debugging tools, exceptions, mysqli, more advanced MySQL statements, and caching. I’ve learned about the differences between versions of software such as PHP, which had monumental changes from PHP4 to PHP5. Most importantly, I learned proper software development in a university course. Looking back, every mistake I made during the design of the old CMS I have learned from, and I’m willing to make a mistake if it means that I learn from it.

Another big change I’m making is that I am going Open Source: letting anyone take a look at the source code. I’m sticking with a Creative Commons license, which allows anyone to take the code, modify it, and redistribute it for free, providing they give me credit for the original work. I think it’s the right choice to make, sticking with the hacker mentality and whatnot. With a goal of distributing knowledge and information to the masses, I think the open source route is a logical step to achieving that.

I started off the development of the new CMS quite differently than before; rather than jumping straight into the coding, I started off old-school: with a pen and paper. Design before development helped ensure everything stayed organized this time. Developing class-by-class, piece by piece allowed for logical places to start and stop work.

The part about this CMS that I am most proud of, however, is that security is added and implemented standard – not as an afterthought. Being interested in security, this seemed like a no-brainer, but it seemed to be either non-existant, poorly implemented, or at the expense of efficiency in other systems available. By considering both security and efficiency at the same time, I hope to develop a system that maintains both equally.

I always like to see people become involved in my projects. If someone is interested in helping with the development, let me know, and maybe something can be arranged.

Ohloh Page:

Project Trac Page: