Update README instructions
diff --git a/README.md b/README.md
index 3c60c38..7a81ef2 100644
--- a/README.md
+++ b/README.md
@@ -19,67 +19,134 @@
[](https://travis-ci.org/apache/geode-site) [](https://www.apache.org/licenses/LICENSE-2.0)
+
# Apache Geode Site
-This directory contains the source files for the project [website](https://geode.apache.org). Website content is written in [Markdown](https://help.github.com/articles/markdown-basics) and the site files are generated from that source by a tool called [Pandoc](http://johnmacfarlane.net/pandoc).
+This repository contains the source files for the [Apache Geode website](https://geode.apache.org).
-Source files for the website are in `website/content`. Generated files for the website are in `build/content`.
+The repository contains two branches:
-**NOTE:** To make changes to the [Apache Geode User Guide](http://geode.apache.org/docs/), which is published to the website:
+- The __master__ branch contains the site's framework, comprised of the top-level landing page and the next level of pages, such as Docs, Community, and Releases, and the tools needed to compile the deployable site.
-- Review [CONTRIBUTING](https://github.com/apache/geode/blob/develop/geode-docs/CONTRIBUTE.md) in the Geode repository for information about contributing to the documentation source files.
-- Follow the [README](https://github.com/apache/geode/blob/develop/geode-book/README.md) in the Geode repository's `geode-book` directory for information about building a local version of the guide and adding it to the website.
+ Most content resides under the `website/content` directory. These sources are compiled into a deployable site by gradle scripts using a tool called [Pandoc](http://johnmacfarlane.net/pandoc).
-The website is updated by a "sync" tool that monitors the __asf-site__ branch
-of our Git repo, so after making changes you must place your updated source
-and generated files on the __asf-site__ branch and push.
-The content will be published to the
+- The __asf-site__ branch contains a copy of the deployable site built from the __master__ branch, fleshed-out with __externally-generated__ content such as the User Guide and the Javadocs, which you build separately then add manually before publishing the completed site.
+
+ To deploy the Apache Geode website, you push the __asf-site__ branch to the upstream Apache repository. An Apache "sync" tool monitors the __asf-site__ branch
+of the repository and publishes your update to the
[Geode website](http://geode.apache.org) after a 5-10 minute delay.
+
+# Update procedure
+Updating the website is a two-part process:
+
+1. On the __master__ branch, update the website's framework pages.
+
+1. Check out the __asf-site__ branch and add externally-generated content, such as the User Guide and the Javadocs.
+
+When the site's updated framework has been fleshed-out with external content, the site is ready to be deployed.
+
## Prerequisites
To generate the site locally, you need to install java and docker.
-## How to change/update the website
+## Update the website framework
-### 1. Find and edit the source files you need to change
+On the __master__ branch, update the website's framework pages. For a general release, this would likely include:
-Source files for the website are in ``website/content``. When changing the content of the site, find the Markdown files that you
-need to edit and make your change. If you need to change the layout or styling of the site, then you will probably need to change
+ - {geode-site}/website/content/index.html
+ - {geode-site}/website/content/community/index.html
+ - {geode-site}/website/content/docs/index.html
+ - {geode-site}/website/content/releases/index.html
+ - If you need to change the layout or styling of the site, then you will probably need to change
an HTML, JS or CSS file.
-### 2. Locally generate the site and test your changes
-To generate the site content, navigate to the top level directory of the repo and use gradle to run the `nanoc` compiler:
+## Locally generate the site framework and review your changes
+You should still be on the __master__ branch.
+
+1. Generate the site content by navigating to the top level directory of the `geode-site` repo and using gradle to compile the sources into a deployable site framework:
+
+ ```
$ ./gradlew compile
+ ```
+2. View the generated site by running:
-To view the generated site, run:
-
+ ```
$ ./gradlew view
+ ```
+
+ and point your browser at `http://localhost:3000` to view the result.
-and point your browser at `http://localhost:3000`. To make further changes, stop the build, edit files, recompile, and view again.
+3. To make further changes, stop the build (Ctrl-C), edit files, recompile, and view again.
-### 3. Publish your changes to the site
+4. Once you are happy with your changes, commit them to the __master__ branch and push them to the upstream Apache repository.
-Once you are happy with your changes, commit them to the __master__ branch.
-The changes also need to be propagated to the __asf-site__ branch. Run the
-gradle command
+## Add externally-generated content to the site framework
+
+### 1. On the __master__ branch, run the gradle command:
$ ./gradlew publish
-to checkout the __asf-site__ branch and copy the website files. You will
-need to manually commit and push your changes on the __asf-site__ branch.
+ The gradle `publish` target:
-The site should update in 5-10 minutes. If it does not,
+ - Checks out the __asf-site__ branch, and
+ - Copies the website files to their deployment directories.
-- Push a new commit by adding or subtracting a blank line, or
+
+### 2. Add a new user guide
+
+1. Create a local build of the User Guide as described in `{geode-project-dir}/geode-book/README.md`.
+
+1. Copy the User Guide to the `geode-site` repo:
+
+ 1. On the __asf-site__ branch, create a destination directory for the User Guide. The naming convention is:
+
+ ```
+ {geode-site}/website/content/docs/guide/XY
+ ```
+ where `XY` is the product version of your documentation (e.g., `{geode-site}/website/content/docs/guide/17` if you are publishing the documentation for Apache Geode 1.7). So, if your current working directory is the top level of `{geode-site}`, you would create the destination directory with the following command:
+
+ ```
+ $ mkdir -p {geode-site}/website/content/docs/guide/XY
+ ```
+
+ 1. Navigate to the User Guide you have built in the Geode repository: `{geode-project-dir}/geode-book/final_app/public/docs/guide/XY`.
+
+ 1. Use `tar` to copy the directory in order to preserve links and other filesystem niceties.
+
+ - Create the tarfile in your Desktop for easy access on the retrieval side.
+
+ ```
+ $ tar cvf ~/Desktop/new-guide-content.tar .
+ ```
+
+ - Navigate to the target directory and un-tar the userguide archive:
+
+ ```
+ $ cd {geode-site}/website/content/docs/guide/XY
+ $ tar xvf ~/Desktop/new-guide-content.tar
+ ```
+
+### 3. Publish new javadocs
+
+You should still be on the __asf-site__ branch. Copy new javadocs directly to the directory
+`{geode-site}/releases/latest/javadoc/`.
+
+The new javadocs _replace_ those currently within the directory.
+
+## Deploy the update
+Commit and push the __asf-site__ branch. Apache detects the update and publishes it. The site should update in 5-10 minutes.
+
+## Troubleshooting
+If the site does not update in 5-10 minutes, __push a new commit by adding or subtracting a blank line in the top-level `index.html` file.__ This usually does the trick.
+
+For further assistance, you can
- [file a JIRA against the INFRA project](https://issues.apache.org/jira/browse/INFRA), or
-- ask for advice on the Infrastructure project's HipChat room
-[#asfinfra](https://www.hipchat.com/g4P84gemn).
+- ask for advice on the Infrastructure project's HipChat room [#asfinfra](https://www.hipchat.com/g4P84gemn).
-### 4. Publishing new javadocs
-Commit and push new javadocs directly on the __asf-site__ branch.
-New javadocs _replace_ those currently within the directory
-`geode-site/releases/latest/javadoc/`.
+
+
+
