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 Mon, 27 Jul 2009 21:42:17 GMT
On Mon, 2009-07-20 at 23:10 -0500, Daniel Spiewak wrote:
> Committed in r796137.
Great!

In the meantime, I handed the quickstart to some collegues of me and
they gave the following feedback:

====
The sentence
"So far, we have seen how Buildr can automatically infer what amounts to
dozens of lines of build.xml contents, all based on a buildfile and a
directory structure."
is not very clear:
-> what about
"So far, we have seen how Buildr can automatically infer what is
expressed with dozens of lines of build.xml contents. Buildr does this
all based on a buildfile and a directory structure."

====
Both ruby and buildr should have a consistent case: Ruby/ruby?
Buildr/buildr?

====
Is it worth to provide an overview over the built in tasks (compile,
package, clean, ...), or at least mention, that "buildr -T" is very
helpful?

====
One developer said it would be helpful to show, how artifacts can be
defined from locally stored jars

====
The question araised if buildr has any support for archetypes. I said
that's not the case, right?

What do you think of these points? Shall some of this make it into the
quickstart?

Cheers,
Martin


> 
> Daniel
> 
> On Sun, Jul 19, 2009 at 3:33 PM, Martin Grotzke <
> martin.grotzke@javakaffee.de> wrote:
> 
> > Ok,
> >
> > cheers,
> > Martin
> >
> >
> > On Sat, 2009-07-18 at 21:45 -0500, Daniel Spiewak wrote:
> > > I like most of what you've changed.  I'm going to reword some stuff, add
> > a
> > > couple things back in, but on the whole I think it's good.  One thing I
> > > would suggest is that you rebase -i the documentation commits on top of
> > > trunk, rather than my master.  Actually, I've already done it for you,
> > > though I edited things slightly during the merge, so it's not an exact
> > > rebase.  Your commits are now incorporated into my quickstart branch:
> > >
> > > git://github.com/djspiewak/buildr.git / quickstart
> > >
> > > Once I make my changes, I'll push them up so that you can see.  Once
> > we're
> > > happy with the results, I'll rebase down to three or so commits
> > (crediting
> > > you appropriately in the commit messages) and dcommit into the SVN.
> > >
> > > Daniel
> > >
> > > On Sat, Jul 18, 2009 at 8:08 PM, Martin Grotzke <
> > > martin.grotzke@javakaffee.de> wrote:
> > >
> > > > hi,
> > > >
> > > > now I have shortened the quickstart a little bit. reading the whole doc
> > > > was fun btw! :)
> > > >
> > > > the buildr clone url is
> > > >  http://github.com/magro/buildr/tree/master
> > > >
> > > > cheers,
> > > > martin
> > > >
> > > >
> > > >
> > > > On Wed, 2009-07-15 at 13:55 -0500, Daniel Spiewak wrote:
> > > > > > that's a really good idea! And a great quick start!
> > > > >
> > > > >
> > > > > Thanks!
> > > > >
> > > > >
> > > > > > 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.
> > > > >
> > > > >
> > > > > True, @artifacts@ can be omitted, especially since @build@ takes
> > care of
> > > > > that for you.  As for the very last bits about Rake tasks, I really
> > think
> > > > > that should be left in some form.  Maybe we could simplify things
a
> > bit,
> > > > but
> > > > > custom tasks are such a fundamental part of Buildr, I don't think
we
> > can
> > > > > just ignore them, even for a quick start.
> > > > >
> > > > >
> > > > > > 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.
> > > > >
> > > > >
> > > > > Agreed.  Short and sweet.
> > > > >
> > > > >
> > > > > > 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.
> > > > >
> > > > >
> > > > > See my other email on this one.  To summarize, I think the concepts
> > > > > presented in such tutorials would be so alike as to really merit
> > merging
> > > > > into one, as I have done.  Maybe we could add a few p(tip) sections
> > about
> > > > > "such-in-such in Ant/Maven equals this-and-that in Buildr"?
> > > > >
> > > > >
> > > > > > So if I can help with anything please let me know :)
> > > > >
> > > > >
> > > > > Famous last words.  :-)  I hardly consider my text to be sacred,
so
> > if
> > > > you
> > > > > feel like a section needs to be deleted, a paragraph needs to be
> > added,
> > > > or a
> > > > > sentence needs to be re-worded, please, feel free!  I seem to recall
> > that
> > > > > you cloned the Git repo.  Feel free to make changes and commit the
> > > > results.
> > > > > If you give me a public clone URL for your repo, I'll pull your
> > changes,
> > > > > review and push them up to the SVN.  This is just documentation
> > stuff, so
> > > > I
> > > > > don't think that a separate ASF agreement is necessary.  (is it?)
> > > > >
> > > > > Daniel
> > > >
> > --
> > Martin Grotzke
> > http://www.javakaffee.de/blog/
> >

Mime
View raw message