readme details about directories

README.markdown

@@ -1,15 +1,59 @@
 ## neo4j.org website
 
-neo4j.org is generated using Octopress to manage pages and blog posts.
+A draft neo4j.org generated using Octopress to manage pages and blog posts.
+
+### Getting started
+
+This is a dev-friendly project for building a website, easily extensible
+into a full web application. That also means it is a little un-friendly
+for normal people. What's that sound? Oh yeah, opportunity knocking.
+
+So. You'll need these tools installed:
+
+* ruby 1.9.2+
+* git 1.7+
+
+**On a Mac?** Cool. You can try the hacked-up `install` script to lead you through installing
+the needed command line tools. If you're feeling brave, you can do this:
+
+  curl https://raw.github.com/neo4j-contrib/neo4j-website/master/install | bash
+
+Optionally, install the Mac [github application](http://mac.github.com) and ask it to "Install command line utility".
+
+Either way, you'll need to set up a github account to use git. Follow the [great instructions](https://help.github.com/articles/set-up-git).
+
+Did you install `rvm`? It'll notice a .rvmrc file and use that to download some stuff needed by ruby.
+Otherwise you'll need to install bundler, then ask it to install some extra things:
+
+  `gem install bundler`
+  `bundle install`
+
+Phew. OK, now you really should be ready. 
 
 ### How-to
 
-1. create a blog post: `rake new_post["title"]`
-2. create a page: `rake new_page[super-awesome/page.html]`
-3. preview the site: `rake preview`
-4. publish: `git push heroku master`
+The project uses a ruby `rakefile` to do perform operations. A `rakefile` is like the
+classic `C` `makefile` but for ruby. 
+
+- create a blog post: `rake new_post["title"]`
+- create a page: `rake new_page[super-awesome/page.html]`
+- preview the site: `rake preview`
+
+Staying up to date, or publishing your changes is done with `git`:
+- update local: `git pull origin master`
+- commit local changes: `git commit -am 'hooray for updates'`
+- share changes: `git push origin master`
+- publish to heroku hosting: `git push heroku master`
+
+See [Octopress Blogging](http://octopress.org/docs/blogging/) for details.
+
+## Directories (& some files)
+
+- [.](/tree/master/source) : top-level project directory 
+- [./_config.yml](/tree/master/_config.yml) : configuration and site-wide variables
+- [./source](/tree/master/source) : raw html, markup, css, images and javascript files. edit these
+- [./public](/tree/master/public) : the generated website. **do not edit**
 
-See [Octopress Bloggin](http://octopress.org/docs/blogging/) for details.
 
 ## What is Octopress?
 

install

@@ -18,16 +18,16 @@ require() {
 }
 
 require "ruby" "--version" "ruby" "ruby should be pre-installed" "Panic, or ask a friend for help."
-require "brew" "--version" "0.9.2" "get it now" "because it is teh awesome"
+require "brew" "--version" "0.9.2" "ruby <(curl -fsSkL raw.github.com/mxcl/homebrew/go)" "Homebrew helps install all kinds of command line goodness."
 require "rvm" "version" "1.15" "curl -L https://get.rvm.io | bash -s stable" "rvm helps with ruby. After installing,\nrun 'rvm requirements' then follow directions under Xcode 4.2 and Homebrew."
 require "ruby" "--version" "1.9.3" "rvm install 1.9.3" "ruby is used for combinining markup with templates to generate the site" 
 require "git" "--version" "git" "brew install git" "git is used for version control of files"
 
-echo "Looks like you are ready to blog! Probably, mostly."
+echo "Looks like you are all ready! Probably, mostly."
 echo ""
 echo "Do you have a github account, and membership in the neo4j-contrib Web Masters team? Ask @akollegger."
 echo ""
-echo "If you haven't cloned the repository yet do this:"
+echo "With an account, you can then clone the repository by doing this:"
 echo "git clone git@github.com:neo4j-contrib/neo4j-website.git"
 echo ""
 echo "Finally. Read the readme."