High Of Solipsism

So here’s a post. A post about how much RDoc sucks. It’s one of those posts, really. The kind that you read and think, “Yeah, man that does suck. I’ve never really liked it.” It’s not however, like those posts where you read and think, “Wow, this guy is just complaining. Why doesn’t he do anything to fix the situation?” I wouldn’t write that kind of post, promise.

So what does this post have to say? I’ll say it again: RDoc sucks, and here’s why:

• RDocs is slow. It’s so slow that I always suggest to newbies that they add --no-rdoc --no-ri to all gem installs.
• RDocs is hardly portable and very icky to maintain.
• RDocs stores a lot in HTML, like an old man programmer. Ruby is DRY. HTML beats DRY like a bad husband.
• RDoc is really slow.

The things you want in a documentation system are four fold:

• Portability
• Maintainability
• Readability
• Speedability

OK, I made that last one up. There’s no such thing as “Speedability,” but you do want your documentation program to be fast (Super fast!). Since RDoc doesn’t match any of these I propose a solution project. I’ll call it gem-runes and it’ll be an adorable little thing. It will use modern technology to solve a very old problem: Documenting code. Here are some features that it would have (Just some ideas!):

• Store all data in SQLite files. Scripts to translate into YAML, JSON, etc.
• Have a checksum for each file to check against for changes.
• Dynamically display files using HAML/SASS on a web server.
• Render comments using Markdown/Textile.
• An API so you can pull from gem-runes instead of using gem-runes.
• Better visual flow of information (3 vertical panels?)

Ultimately the idea is that gem-runes should replace RDocs for gem and ruby project documentation. It should be something developers enjoy interacting with, because we humans tend to do things we enjoy.

Posted on September 7 2010