buildr-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Alex Boisvert <boisv...@intalio.com>
Subject Re: Quick Start Documentation
Date Wed, 15 Jul 2009 17:29:25 GMT
+1 on "Buildr for Maven users" and "Buildr for Ant users";  I think most of
our users are refugees and giving them an introduction that illustrates
common patterns and examples from Ant/Maven converted to Buildr would be a
great evangelization^H^H^H^H^H^H^H^H^H^Hmigration tactic.

My other documentation wish lists are 1) FAQ, 2) something that introduces
Rake and how it relates to Buildr 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
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message