diff --git a/README.md b/README.md
index 0a11c602..cb0da3cd 100644
--- a/README.md
+++ b/README.md
@@ -1,20 +1,64 @@
-# rpm-ostree
-A system to compose RPMs on a server side into an
-[OSTree](https://wiki.gnome.org/Projects/OSTree)
-repository, and a client side tool to perform updates.
+# rpm-ostree Overview
+
+New! See the docs online at [Read The Docs (rpm-ostree)](https://rpm-ostree.readthedocs.org/en/latest/ )
+
+-----
+
+rpm-ostree is a hybrid image/package system.  It uses
+[OSTree](https://wiki.gnome.org/Projects/OSTree) as an image format,
+and uses RPM as a component model.
 
 The project aims to bring together a hybrid of image-like upgrade
 features (reliable replication, atomicity), with package-like
-flexibility (seeing package sets inside trees, layering, partial live
-updates).
+flexibility (introspecting trees to find package sets, package
+layering, partial live updates).
 
-## rpm-ostree is in beta!
-While many of the underlying technologies here are stable,
-if you are considering using this in your organization, you
-should perform a careful evaluation of the whole stack.  Software
-updates are obviously critical, and touch on many areas of concern.
+**Features:**
+
+ - Atomic upgrades and rollback for host system updates
+ - A server side tool to consume RPMs and commit them to an OSTree repository
+ - A system daemon to consume ostree commits as updates
+
+Projects using rpm-ostree
+-------------------------
+
+[Project Atomic](http://www.projectatomic.io/) uses rpm-ostree to
+provide a minimal host for Docker formatted Linux containers.
+Replicating a base immutable OS, then using Docker for applications.
+
+Building
+--------
+
+Releases are available as GPG signed git tags, and most recent
+versions support extended validation using
+[git-evtag](https://github.com/cgwalters/git-evtag).
+
+However, in order to build from a git clone, you must update the
+submodules.  If you're packaging and want a tarball, I recommend using
+a "recursive git archive" script.  There are several available online;
+[this code](https://git.gnome.org/browse/ostree/tree/packaging/Makefile.dist-packaging#n11)
+in OSTree is an example.
+
+Once you have a git clone or recursive archive, building is the
+same as almost every autotools project:
+
+```
+env NOCONFIGURE=1 ./autogen.sh
+./configure --prefix=...
+make
+make install DESTDIR=/path/to/dest
+```
+
+More documentation
+------------------
+
+New! See the docs online at [Read The Docs (OSTree)](https://ostree.readthedocs.org/en/latest/ )
+
+Some more information is available on the old wiki page:
+https://wiki.gnome.org/Projects/OSTree
+
+Contributing
+------------
+
+See [Contributing](CONTRIBUTING.md).
 
-### Contents
-* [Background and rationale](doc/background.md)
-* [Setting up and managing a compose server](doc/compose-server.md)
-* [Administering an rpm-ostree system](doc/administrator-handbook.md)
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
new file mode 100644
index 00000000..f55af955
--- /dev/null
+++ b/docs/CONTRIBUTING.md
@@ -0,0 +1,17 @@
+Submitting patches
+------------------
+
+Submit a pull request against <https://github.com/projectatomic/rpm-ostree>.
+
+Please look at "git log" and match the commit log style.
+
+Running the test suite
+----------------------
+
+Use `make check` for now.
+
+Coding style
+------------
+
+See the [OSTree CONTRIBUTING](https://git.gnome.org/browse/ostree/tree/docs/CONTRIBUTING.md)
+coding style.
diff --git a/docs/index.md b/docs/index.md
new file mode 120000
index 00000000..32d46ee8
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1 @@
+../README.md
\ No newline at end of file
diff --git a/doc/administrator-handbook.md b/docs/manual/administrator-handbook.md
similarity index 100%
rename from doc/administrator-handbook.md
rename to docs/manual/administrator-handbook.md
diff --git a/doc/background.md b/docs/manual/background.md
similarity index 100%
rename from doc/background.md
rename to docs/manual/background.md
diff --git a/doc/compose-server.md b/docs/manual/compose-server.md
similarity index 100%
rename from doc/compose-server.md
rename to docs/manual/compose-server.md
diff --git a/doc/treefile.md b/docs/manual/treefile.md
similarity index 96%
rename from doc/treefile.md
rename to docs/manual/treefile.md
index 559d17b3..59bb7844 100644
--- a/doc/treefile.md
+++ b/docs/manual/treefile.md
@@ -1,6 +1,15 @@
 Treefile
 --------
 
+A "treefile" is a made up term for a JSON-formatted specification used
+as input to `rpm-ostree compose tree` to bind "set of RPMs with
+configuration" to "OSTree commit".
+
+It's recommended to keep them in git, and set up a CI system like
+Jenkins to operate on them as it changes.
+
+It supports the following parameters:
+
  * `ref`: string, mandatory: Holds a string which will be the name of
    the branch for the content.
 
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 00000000..b85da331
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,9 @@
+site_name: rpm-ostree
+pages:
+  - Home: 'index.md'
+  - Contributing: 'CONTRIBUTING.md'
+  - Manual:
+      - Background: 'manual/background.md'
+      - Client Administration: 'manual/administrator-handbook.md'
+      - Compose Server: 'manual/compose-server.md'
+      - Treefile: 'manual/treefile.md'