buildr-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Assaf Arkin <as...@labnotes.org>
Subject Re: Quick Start Documentation
Date Wed, 15 Jul 2009 06:27:33 GMT
On Tue, Jul 14, 2009 at 10:06 PM, Daniel Spiewak <djspiewak@gmail.com>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?


Big +1

Assaf


>
>
> Daniel
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message