Tim Bray pointed to a new build tool called Buildr. It’s written in Ruby, and provides an easy-to-write DSL for declaring rules. But the only documentation is the rdoc. There are no examples and no “Getting Started” info that I can find in the docs.
Aaah, a Google search finds the introductory blog post, which Tim did point to and which is slightly useful. At least the authors point to some rake files you can learn from. At the very least, the rdoc Readme (which the home page redirects to) should have pointed here.
I know, it’s a beta, it’s brand new and the developers could not wait to put it out there for their friends to oooh and aaah over. But if you really want us to try it out point us to something more than the rdocs (and this means you too, Tim, “Buildr” should link to something actually useful). This reminds me of the bad old days when all Java code just shipped with the JavaDocs and that was “enough”. The API is not the documentation, folks. It’s a useful part of the documentation, but it’s not enough.
It absolutely gets me hot under the collar when I go to read about some new code and all I get is the API doc. Treat us with respect, people. Take the time to give us a good introduction (this was a start at least), an FAQ, a variety of example apps or code samples, and THEN a pointer to the API docs.
Rdoc has its place, but that place is not your project’s home page.
GRUMBLE GRUMBLE
Leave a comment