diff --git a/.gitignore b/.gitignore
index 0b129e03..32d466a7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,6 +10,7 @@
 build
 bin
 /target/
+asciidoctor.css
 _site/
 *.swp
 .idea
diff --git a/Guardfile b/Guardfile
new file mode 100644
index 00000000..6e8389bf
--- /dev/null
+++ b/Guardfile
@@ -0,0 +1,12 @@
+require 'asciidoctor'
+require 'erb'
+
+options = {:mkdirs => true, :safe => :unsafe, :attributes => 'linkcss'}
+
+guard 'shell' do
+  watch(/^[A-Za-z].*\.adoc$/) {|m|
+    Asciidoctor.load_file('src/main/asciidoc/README.adoc', :to_file => './README.adoc', safe: :safe, parse: false)
+    Asciidoctor.render_file('src/main/asciidoc/spring-cloud-build.adoc', options.merge(:to_dir => 'target/generated-docs'))
+    Asciidoctor.render_file('src/main/asciidoc/building.adoc', options.merge(:to_dir => 'target/generated-docs'))
+  }
+end
diff --git a/pom.xml b/pom.xml
index e7ff8859..18e2cc60 100644
--- a/pom.xml
+++ b/pom.xml
@@ -79,6 +79,11 @@
 					<artifactId>replacer</artifactId>
 					<version>1.5.3</version>
 				</plugin>
+		        <plugin>
+		          <groupId>org.asciidoctor</groupId>
+		          <artifactId>asciidoctor-maven-plugin</artifactId>
+		          <version>1.5.0</version>
+                </plugin>
 			</plugins>
 		</pluginManagement>
 	</build>
@@ -133,7 +138,6 @@
 		          <plugin>
 		            <groupId>org.asciidoctor</groupId>
 		            <artifactId>asciidoctor-maven-plugin</artifactId>
-		            <version>1.5.0</version>
 		            <executions>
 			          <execution>
 			            <id>generate-docs</id>
diff --git a/src/main/asciidoc/README.adoc b/src/main/asciidoc/README.adoc
new file mode 100644
index 00000000..a0a23ed9
--- /dev/null
+++ b/src/main/asciidoc/README.adoc
@@ -0,0 +1,3 @@
+Spring Cloud Build is a common utility project for Spring Cloud
+to use for plugin and dependency management.
+
diff --git a/src/main/asciidoc/building.adoc b/src/main/asciidoc/building.adoc
new file mode 100644
index 00000000..066f18da
--- /dev/null
+++ b/src/main/asciidoc/building.adoc
@@ -0,0 +1,109 @@
+== Basic Compile and Test
+
+To build the source you will need to install
+http://maven.apache.org/run-maven/index.html[Apache Maven] v3.0.6 or above and JDK 1.7.
+
+Spring Cloud uses Maven for most build-related activities, and you
+should be able to get off the ground quite quickly by cloning the
+project you are interested in and typing
+
+----
+$ mvn install -s .settings.xml
+----
+
+NOTE: You may need to increase the amount of memory available to Maven by setting
+a `MAVEN_OPTS` environment variable with the value `-Xmx512m -XX:MaxPermSize=128m`
+
+The `.settings.xml` is only required the first time (or after updates
+to dependencies). It is there to provide repository declarations so
+that those do not need to be hard coded in the project poms.
+
+For hints on how to build the project look in `.travis.yml` if there
+is one. There should be a "script" and maybe "install" command. Also
+look at the "services" section to see if any services need to be
+running locally (e.g. mongo or rabbit).  Ignore the git-related bits
+that you might find in "before_install" since they will be able git
+credentials and you already have those.
+
+If you need mongo, rabbit or redis, see the README in the [scripts
+demo repository](https://github.com/spring-cloud-samples/scripts) for
+instructions. For example consider using the "fig.yml" with
+[Fig](http://www.fig.sh/) to run them in Docker containers.
+
+== Documentation
+
+The spring-cloud-build module has a "docs" profile, and if you switch
+that on it will try to build asciidoc sources from
+`src/main/asciidoc`. As part of that process it will look for a
+`README.adoc` and process it by loading all the includes, but not
+parsing or rendering it, just copying it to `${main.basedir}`
+(defaults to `${basedir}`, i.e. the root of the project). If there are
+any changes in the README it will then show up after a Maven build as
+a modified file in the correct place. Just commit it and push the change.
+
+== Pull Requests
+
+Spring Cloud is released under the non-restrictive Apache 2.0 license,
+and follows a very standard Github development process, using Github
+tracker for issues and merging pull requests into master. If you want
+to contribute even something trivial please do not hesitate, but
+follow the guidelines below.
+
+=== Sign the Contributor License Agreement
+Before we accept a non-trivial patch or pull request we will need you
+to sign the 
+https://support.springsource.com/spring_committer_signup[contributor's
+agreement].  Signing the contributor's agreement does not grant anyone
+commit rights to the main repository, but it does mean that we can
+accept your contributions, and you will get an author credit if we do.
+Active contributors might be asked to join the core team, and given
+the ability to merge pull requests.
+
+=== Code Conventions and Housekeeping
+None of these is essential for a pull request, but they will all help.  They can also be
+added after the original pull request but before a merge.
+
+* Use the Spring Framework code format conventions. If you use Eclipse and you follow
+  the ``Importing into eclipse'' instructions below you should get project specific
+  formatting automatically. You can also import formatter settings using the
+  `eclipse-code-formatter.xml` file from the `eclipse` folder. If using IntelliJ, you can
+  use the http://plugins.jetbrains.com/plugin/6546[Eclipse Code Formatter Plugin]
+  to import the same file.
+* Make sure all new `.java` files to have a simple Javadoc class comment with at least an
+  `@author` tag identifying you, and preferably at least a paragraph on what the class is
+  for.
+* Add the ASF license header comment to all new `.java` files (copy from existing files
+  in the project)
+* Add yourself as an `@author` to the .java files that you modify substantially (more
+  than cosmetic changes).
+* Add some Javadocs and, if you change the namespace, some XSD doc elements.
+* A few unit tests would help a lot as well -- someone has to do it.
+* If no-one else is using your branch, please rebase it against the current master (or
+  other target branch in the main project).
+
+=== Working with the code
+If you don't have an IDE preference we would recommend that you use
+http://www.springsource.com/developer/sts[Spring Tools Suite] or
+http://eclipse.org[Eclipse] when working with the code. We use the
+http://eclipse.org/m2e/[m2eclipe] eclipse plugin for maven support. Other IDEs and tools
+should also work without issue.
+
+=== Importing into eclipse with m2eclipse
+We recommend the http://eclipse.org/m2e/[m2eclipe] eclipse plugin when working with
+eclipse. If you don't already have m2eclipse installed it is available from the "eclipse
+marketplace".
+
+=== Importing into eclipse without m2eclipse
+If you prefer not to use m2eclipse you can generate eclipse project metadata using the
+following command:
+
+[indent=0]
+----
+	$ mvn eclipse:eclipse
+----
+
+The generated eclipse projects can be imported by selecting `import existing projects`
+from the `file` menu.
+
+=== Importing into other IDEs
+Maven is well supported by most Java IDEs. Refer to you vendor documentation.
diff --git a/src/main/asciidoc/ghpages.sh b/src/main/asciidoc/ghpages.sh
new file mode 100755
index 00000000..91905757
--- /dev/null
+++ b/src/main/asciidoc/ghpages.sh
@@ -0,0 +1,46 @@
+#!/bin/bash -x
+
+git remote set-url --push origin `git config remote.origin.url | sed -e 's/^git:/https:/'`
+
+if ! (git remote set-branches --add origin gh-pages && git fetch -q); then
+    echo "No gh-pages, so not syncing"
+    exit 0
+fi
+
+if ! [ -d docs/target/generated-docs ]; then
+    echo "No gh-pages sources in docs/target/generated-docs, so not syncing"
+    exit 0
+fi
+
+# Stash any outstanding changes
+###################################################################
+git diff-index --quiet HEAD
+dirty=$?
+if [ "$dirty" != "0" ]; then git stash; fi
+
+# Switch to gh-pages branch to sync it with master
+###################################################################
+git checkout gh-pages
+
+for f in docs/target/generated-docs/*; do
+    file=${f#docs/target/generated-docs/*}
+    if ! git ls-files -i -o --exclude-standard --directory | grep -q ^$file$; then
+        # Not ignored...
+        cp -rf $f .
+        git add -A $file
+    fi
+done
+
+git commit -a -m "Sync docs from master to gh-pages"
+
+# Uncomment the following push if you want to auto push to
+# the gh-pages branch whenever you commit to master locally.
+# This is a little extreme. Use with care!
+###################################################################
+git push origin gh-pages
+
+# Finally, switch back to the master branch and exit block
+git checkout master
+if [ "$dirty" != "0" ]; then git stash pop; fi
+
+exit 0
diff --git a/src/main/asciidoc/spring-cloud-build.adoc b/src/main/asciidoc/spring-cloud-build.adoc
new file mode 100644
index 00000000..52e87c18
--- /dev/null
+++ b/src/main/asciidoc/spring-cloud-build.adoc
@@ -0,0 +1,3 @@
+= Spring Cloud Build
+
+include::README.adoc
diff --git a/src/main/ruby/generate_readme.sh b/src/main/ruby/generate_readme.sh
new file mode 100755
index 00000000..fc5b7f1a
--- /dev/null
+++ b/src/main/ruby/generate_readme.sh
@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+
+base_dir = File.join(File.dirname(__FILE__),'../../..')
+src_dir = File.join(base_dir, "/src/main/asciidoc")
+require 'asciidoctor'
+require 'optparse'
+
+options = {}
+file = "#{src_dir}/README.adoc"
+
+OptionParser.new do |o|
+  o.on('-o OUTPUT_FILE', 'Output file (default is stdout)') { |file| options[:to_file] = file unless file=='-' }
+  o.on('-h', '--help') { puts o; exit }
+  o.parse!
+end
+
+file = ARGV[0] if ARGV.length>0
+
+srcDir = File.dirname(file)
+out = "// Do not edit this file (e.g. go instead to src/main/asciidoc)\n\n"
+doc = Asciidoctor.load_file file, safe: :safe, parse: false
+out << doc.reader.read
+
+unless options[:to_file]
+  puts out
+else
+  File.open(options[:to_file],'w+') do |file|
+    file.write(out)
+  end
+end