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?
Continue reading “The curse of blogs and vidcasts”