I was thinking back to when I was first getting into Buildr and I remembered my initial thoughts on the documentation. To be honest, Buildr has some of the best documentation of any open-source project I have ever seen (major props, Assaf). However, stop number one in the guide is a *very* complex project, one which is far more convoluted and confusing than anything a complete newcomer is going to have to deal with. One of the problems I had was in distinguishing all of those confusing methods, trying to figure out what was necessary for my simple test project and what was simply trappings for the massive beast in the tutorial. Don't get me wrong, it's good that the stuff is documented, but we need something which offers a gentler slope for absolute beginners -- including those with no previous experience with Ruby.
To that end, I've been experimenting with a slight reorganization of the documentation. Basically, all the old stuff is intact, but I renamed "Getting Started" to "Setup Guide" to reflect the fact that it's really all about installation and I have written a rather long "Quick Start" introduction. All of the information included in this quick start is available elsewhere in the documentation, but this distills it slightly and filters out most of the really powerful stuff. In other words, I talk about how to specify artifacts, but I don't even hint at how you can download them by hand using an artifact(...) task. You can find all this in my Git clone: git://github.com/djspiewak/buildr.git/ quickstart Or, if you just want to read the new material: http://github.com/djspiewak/buildr/blob/fa9d7a9c58585ec7ebc2e3ac01fb6b6a127aba15/doc/quick_start.textile What is the general opinion on this? Does this sort of "redundant quick start" seem like a good idea to anyone else? Daniel
