buildr-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Daniel Spiewak <djspie...@gmail.com>
Subject Quick Start Documentation
Date Wed, 15 Jul 2009 05:06:12 GMT
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

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