On Wed, 2009-07-15 at 10:29 -0700, Alex Boisvert wrote: > My other documentation wish lists are 1) FAQ, I think the How-To's in the wiki represent an FAQ.
> 2) something that introduces Rake and how it relates to Buildr +1! Rake tasks are (parts of?) the basic concepts that are important to understand if one really starts using/working with buildr. Cheers, Martin > and 3) a short tutorial/appendix about > Ruby scripting focused on build-oriented tasks (e.g. copying, moving files, > executing external processes, etc.). > > alex > > On Wed, Jul 15, 2009 at 10:16 AM, Martin Grotzke < > [email protected]> wrote: > > > 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
