diff --git a/README.rst b/README.rst
index de71054..57cbd64 100644
--- a/README.rst
+++ b/README.rst
@@ -17,23 +17,42 @@ configuration drive.
 What does glean do?
 -------------------
 
-Glean firstly checks for configuration drive based information and, if
-found, uses that for network configuration.  If config-drive is not
-found, it falls back to configuring any available interfaces with DHCP.
+Broadly, glean checks for configuration drive based information and,
+if found, uses that to configure the network.  If config-drive is not
+found, it falls back to configuring any available interfaces with
+DHCP.
 
 Specifically, it will mount the special block-device with label
 `config-2` and parse the `network_info.json` and `vendor_info.json`
 files within.  If appropriate network configuration is found, it will
-write out network configuration files (e.g. `/etc/sysconfig/network/`
-scripts on Red Hat platforms, `/etc/interfaces` on Debian, etc).
+write out network configuration files.
 
-If no network info is found there, available interfaces will be probed
+If no network info is found there, available interfaces can be probed
 from `/sys/class/net` and any that appear to be up will be configured
 for use with DHCP.
 
 It will also handle `authorized_keys` and host-name info provided from
 `meta_data.json`.
 
+How does glean do this?
++++++++++++++++++++++++
+
+systemd environment
+===================
+
+glean install will add a `udev` rules file (`99-glean.rules`) that
+triggers on any network device being added.  This will run the
+`glean@.service` systemd template for the interface specified.
+
+This systemd unit firstly determines if there is already a
+`/etc/sysconfig/network/` configuration for the interface; if so, the
+interface is considered configured and skipped.
+
+If not, glean is started with the interface specified.  The
+configuration drive is probed to see if network configuration for the
+interface is available.  If so, it will be added, otherwise the
+interface will configured for DHCP.
+
 How do I use glean?
 -------------------
 
@@ -42,8 +61,8 @@ system startup environment.  It should handle `sysv`, `upstart` and
 `systemd` to cover all major distributions.  This should be run once,
 during install or image build.
 
-The startup environment will run `glean.sh`, which configures any
-found interfaces as described above.
+The startup environment will be modified as described above to
+configure any found interfaces.
 
 Differences to cloud-config?
 ----------------------------
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 5ef2a97..f495c63 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -3,22 +3,12 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to glean's documentation!
-========================================================
+.. include:: ../../README.rst
 
-Contents:
+More information
+================
 
 .. toctree::
    :maxdepth: 2
 
-   readme
-   installation
-   usage
    contributing
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
diff --git a/doc/source/installation.rst b/doc/source/installation.rst
deleted file mode 100644
index 3fbfd0e..0000000
--- a/doc/source/installation.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-============
-Installation
-============
-
-At the command line::
-
-    $ pip install glean
-
-Or, if you have virtualenvwrapper installed::
-
-    $ mkvirtualenv glean
-    $ pip install glean
diff --git a/doc/source/readme.rst b/doc/source/readme.rst
deleted file mode 100644
index 38ba804..0000000
--- a/doc/source/readme.rst
+++ /dev/null
@@ -1 +0,0 @@
-.. include:: ../../README.rst
\ No newline at end of file
diff --git a/doc/source/usage.rst b/doc/source/usage.rst
deleted file mode 100644
index f55d7fd..0000000
--- a/doc/source/usage.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-========
-Usage
-========
-
-To use glean in a project::
-
-    import glean