It drives me crazy: Lot’s of those projects, especially in the Rails world think it’s a cool thing to have a “project” homepage that consists of a blog garnished with some video podcasts. But while this may look flashy, it’s not an excuse for a complete absence of structure and documentation.
I have to admit that what put me over the top today was the ruby-debug “home page”. It’s really a great tool that I use daily, but each time I visit this page I’m on the edge.
First thing, it’s a blog. I hate it. A blog is for news, but when I go to this page I want documentation. Yes, there is this little tutorial. If it’s not accidentally linked from a post on the front page I have to dig through all the “ruby-debug” posts to find it. At least it explains all the commands in the debugger, but it doesn’t go into the API to call the debugger from your code.
In the end, what would be so hard to put your documentation on a static page page that is linked from the front page? And maybe – behold – even add a link to the rdoc documentation that you can automatically generate from you code?
Instead (at the time I’m writing this), the top entry of the homepage is this. A link to a screencast:
Brian Donovan shows the basics of using ruby-debug. This is very nice addition to my already outdated tutorial. He also announced that his next screencast will cover debugging of a Rails application.
A nice addition to the outdated tutorial? A nice addition would be an updated tutorial. But I disgress.
The point is I hate, hate, hate those screencasts. Well, not screencasts as such, but projects like Streamlined that don’t even offer screenshots any more. You have to watch those fucking screencasts.
I know it’s really exiting, like being on TV, and it’s easy to – just wiggle your mouse a bit and talk into your mike. But do you honestly believe that I enjoy wasting just 10 minutes of my life to watch you guys typing into Texmate? I know that written documentation is hard to do. You need actual written communication skills (and here you have a chance to develop them). But all your cool mates would have a much easier time actually finding the information they’re looking for.
Up to a point I believe that all those people are following the lead of the Rails homepage. It looks cool and has a vidcast. Did any of you guys notice that it lacks any structured introduction into the framework – except from those very basic tutorials that come from third parties? To get a comprehensive overview you have to shell out real bucks to buy the (admittedly good) book.
The thing is, they can get away with it. But unless you have a book and something that is cool enough to make folks out there actually buy it, please provide some structured documentation.