On Tue, Jul 14, 2009 at 10:06 PM, Daniel Spiewak <[email protected]>wrote:
> 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? Big +1 Assaf > > > Daniel >
