buildr-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Martin Grotzke <martin.grot...@javakaffee.de>
Subject Re: Quick Start Documentation
Date Wed, 15 Jul 2009 18:31:43 GMT
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 <
> martin.grotzke@javakaffee.de> 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/
> >

Mime
View raw message