Hi, that's a really good idea! And a great quick start!
Just some comments: I scanned through your quick start, read the first paragraphs and then began to scroll - it got a little bit too detailed at the end. E.g. for a quick start I'd just mention how dependencies/artifacts are defined, but I would not explain how buildr caches them. For such further information the text could hyperlink to an appropriate section in the full documentation. I'd also ignore things like the artifacts task, as the "normal" build lifecycle does not include this task - at least for me. I'd focus on keeping this quick start as short as possible and leave out (link to) things that are not necessarily required to get the first simple (multi module?) project going, so that new users don't get the impression that buildr is kind of complex or that one needs to read a lot to get the basic things done. Additionally one might create two intros "buildr for maven users" and "buildr for ant users": e.g. for ant users it's definitely important that they can reuse all their ant stuff without pain, and this would also include an example for an ant task/target. I like buildr a lot - it's simply the best build tool I ever worked with and I hope that it's getting more popular with time. In our company I just make the experience that developers (especially those with "more experience") are not really willing to invest time in "learning" a build tool - even if they did (had to) so with maven. Most of them like ant for it's simplicity and as they already know it. If they could get a short quick start that shows how simple and intuitive buildr is this would be definitely a big plus for buildr. So if I can help with anything please let me know :) Cheers, Martin On Wed, 2009-07-15 at 00:06 -0500, Daniel Spiewak 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? > > Daniel -- Martin Grotzke http://www.javakaffee.de/blog/
signature.asc
Description: This is a digitally signed message part
