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 20:10:31 GMT
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.
Well, I'm not sure. The quick start is going to be the first page
(potential) new users have a look at.

For users that already have installed buildr and really want to get
started I think this is not really necessary (unless we find an example
that's so obvious that everybody needs _this_ custom task to get
started, what I currently can't think of). Instead, the new user has to
read more stuff, and the quick start is getting even longer (1/4 or 1/2
of a screen?).

For potential new users that just stumbled over buildr and want to see
what it does this is IMHO more interesting, as it shows how easy it is
to realize a custom requirement like "count loc" or "initialize the db
schema". So it's more one part of getting a quick overview over buildr
and _all_ things buildr can do (not only the absolutely necessary).

For both users that want to get their first project up and running and
those potential-new-users I'd prefer to just mention it and link to a
page with more information. Basically I think the quick start should
just mention what's definitely required and link to everything else.


> 
> 
> > 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"?
Great idea, I really like "Tip" sections! :) Perhaps it's possible that
they do not contribute very much to the length of the page? E.g. by
placing them on the side of the main content or s.th. like this? (you
see it's really important to me, that the quick start remains short :))

> 
> 
> > 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?)
Ok, first I need to get some work done, but perhaps I find some time
later this night. Otherwise I should find time the following days.

Cheers,
Martin


> 
> Daniel



-- 
Martin Grotzke
http://www.javakaffee.de/blog/

Mime
View raw message