Update README.textile

Added basic outline of how to edit and publish the website.

Author: rhauch

README.textile

@@ -2,4 +2,58 @@ h1. !{vertical-align:middle}https://github.com/ModeShape/modeshape.github.com/ra
 
 This repository contains the source of the ModeShape website (hosted using "github pages":http://pages.github.com), to which the "modeshape.org":modeshape.org hostname (will soon) resolves.
 
-The website is built using "Awestruct":awestruct.org. Make changes to the files in the @develop@ branch, which contains the unprocessed website source. Then, use Awestruct locally to transform those files into the static website pages in the @_site@ directory. Then update the public site by pushing the generated contents of the @_site@ directory to the @master@ branch.
+h1. How it works
+
+The website is built using "Awestruct":awestruct.org. This means that all of the source files are Ruby, JavaScript, Haml, Textile, SASS, and Compass files, so editing the site is similar to working on a Ruby web application. However, rather than running a webserver for the site, we use Awestruct to transform those files into a set of static HTML, CSS and JavaScript files that are then pushed up to the website.
+
+All of these source files are hosted in this Git repository on GitHub, within the @develop@ branch. The generated static files, however, are merged onto the @master@ branch, where GitHub Pages recognizes them and publishes them on "modeshape.org":modeshape.org.
+
+h1. Editing and publishing the site
+
+You can use GitHub to edit the pages on the @develop@ branch, but they don't automatically get pushed out to the website. That's because Awestruct must be run locally to generate the static files, which means you'll need a copy of the Git repository on your local machine. 
+
+h2. Setting up your environment
+
+You'll need a couple of things on your local machine before you can work:
+
+* Git
+* Ruby
+* gems
+* Awestruct
+
+Then, create a fork of this repository using the "Fork":https://github.com/ModeShape/modeshape.github.com/fork_select button at the top of this page. Create a local clone of your fork:
+
+bc. $ git clone git@github.com:YourUsername/modeshape.github.com.git
+$ cd modeshape.git.com
+
+
+h2. Editing
+
+Just like with the ModeShape source code, make all changes on a topic branch in your local repository. But unlike your other ModeShape Git repositories, be sure to create your topic branch from the @develop@ branch:
+
+bc. $ git checkout -b _topicbranchname_ develop
+
+Then make your modifications and run Awestruct:
+
+bc. $ awestruct -d
+
+This runs Awestruct in "development" mode, where it watches the local file system for changes and will regenerate any affected files. You can see the website with a browser by pointing to "http://localhost:4242":http://localhost:4242. 
+
+When you're happy with the changes, commit to your branch and push the changes up to your fork:
+
+bc. $ git commit -m "Meaningful description" .
+$ git push origin _topicbranchname_
+
+and then got to your fork repository on GitHub.com and create a pull-request with that topic branch. We'll review the pull-request and, if all looks good, merge those changes into this repository and publish the changes to the website.
+
+h2. Merging and publishing
+
+Only a few key community members have privilege to perform these next steps, so most of you won't have to worry about how this works. But for those of you that do have privilege, the process is similar to merging changes in the ModeShape codebase. 
+
+# merge the changes from the pull-request into the @develop@ branch in this repository
+# use Awestruct to generate the static pages and verify the site looks good and works as expected
+# place the generated static pages into the @master@ branch using the "@_bin/deploy-production.sh@" script
+
+GitHub Pages will recognize the changes, "build" the site (this will generate an email to those watching the repository), and deploy the updated pages to "modeshape.org":modeshape.org.
+
+Everything else should happen automatically.