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 17:16:31 GMT
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