updated README with better info

Author: Andy Perlitch

README.md

@@ -1,39 +1,47 @@
 Apache Apex Incubator Website
 =============================
 
-This is the source code for the Apache Apex Incubator website, hosted at [apex.incubator.apache.org](http://apex.incubator.apache.org/).
+This is the source code for the Apache Apex Incubator website, hosted at [apex.incubator.apache.org](http://apex.incubator.apache.org/). The following tools are used to build the html pages:
+
+- [nodejs + npm](https://nodejs.org/en/)
+- [gulp - nodejs automation tool](http://gulpjs.com/)
+- [handlebars.js - templating](http://handlebarsjs.com/)
+- [LESS - css pre-processor](http://lesscss.org/)
+- [Marked - Markdown parser/compiler](https://github.com/chjj/marked)
+- [Bootstrap - HTML/CSS/JS framework](http://getbootstrap.com/)
+- [jQuery](https://jquery.com/)
 
 
 How it works
 ------------
-The master branch of this repo contains the files that are used to generate the HTML that ultimately gets pushed to the incubator site.
+The master branch of this repo contains the source files that are used to generate the HTML that ultimately gets pushed to the incubator site.
 The `asf-site` branch is where the actual generated files are stored. Note that this branch must contain exactly one folder called `content`,
-and so has been checked out as an orphan branch with its own commit history apart from the master branch. See the *Building* section below.
+and so has been checked out as an orphan branch with its own commit history apart from the master branch. See the *Contributing* section below.
 
 Through a [gitpubsub](http://www.apache.org/dev/gitpubsub.html) mechanism on the apache.org server,
 files are taken from the `asf-branch` and pushed to the live server.
 
-Partials
---------
-All pages on the site share the same header and footer. These are stored in the `src/partials` folder.
-
 Pages
 -----
-Pages are stored in the `src/pages` folder. Each page should look something like this:
+Pages are stored in the `src/pages` folder. Each page uses the [handlebars templating engine](http://handlebarsjs.com/), and should look something like this:
 
 ```HTML
-{{> header}}
+{{> header}} <!-- includes the header.handlebars partial -->
 
 <h1>Hello World</h1>
 <p>I am a page.</p>
 
-{{> footer}}
+{{> footer}} <!-- includes the footer.handlebars partial -->
 ```
 
-## Markdown files
+Partials
+--------
+All pages on the site share the same header and footer. These are stored in the `src/partials` folder. You can put other partials in here and they will be made available to all templates (the `.handlebars` extension is dropped).
 
-If you have a block of content that you would like to render as markdown, you can do so by creating a `.md` file in the `src/md/` folder.
-These will be picked up, rendered has html, and passed into your page templates as partials. 
+Markdown files
+--------------
+If you have a block of content that you would like to render from a markdown file, you can do so by creating a `.md` file in the `src/md/` folder.
+These `.md` files will be picked up, rendered has html, and exposed to page templates as partials. 
 Assuming you have a file called `src/md/example_markdown.md`, you could have this in a page template:
 
 ```HTML
@@ -46,17 +54,36 @@ Assuming you have a file called `src/md/example_markdown.md`, you could have thi
 {{> footer}}
 ```
 
-Building (requires node+npm)
-----------------------------
-Run `build.sh` from the directory. This will:
-
-- ensure the necessary npm and bower dependencies are installed
-- checks out and updates the `asf-site` branch with a new commit of the build from the current branch
-
-You must manually push to the `asf-site` remote branch.
+Contributing
+------------
+If you would like to make a change to the site:
+
+1. Fork the [github mirror](https://github.com/apache/incubator-apex-site)
+2. Create a new branch from `master`
+3. Add commit(s) to your branch
+4. Test your changes locally (see Development section below)
+5. Open a pull request on the github mirror
+6. A committer will merge your changes if all is good
+
+If you are a committer, do the following:
+
+1. Update the master branch with your (or a Pull Request's) change.
+2. Push updated master to the asf remote master (https://git-wip-us.apache.org/repos/asf/incubator-apex-site.git)
+2. Run `build.sh` from the master branch directory (requires nodejs and npm). This will:
+  - ensure the necessary npm and bower dependencies are installed
+  - checks out and updates the `asf-site` branch with a new commit of the build from the current branch
+3. At this point, you should be on the `asf-site` branch. Simply push this branch to the asf remote and the site will automatically be updated within seconds.
+
+Development
+-----------
+To set up the proper dev environment for this site, run the following:
+
+```bash
+npm install
+./node_modules/.bin/bower install
+./node_modules/.bin/gulp watch
+```
 
-Developing
-----------
 
-When making changes to src files, you can run `grunt watch`, which will constantly build the project in the `/content` folder,
-so you don't have to manually run `grunt` after every change
+The `gulp watch` command will start a process that watches for changes to source files and updates the `/content` folder accordingly.
+Simply open `/content/index.html` in your browser and refresh the page when you make changes.