--- a/README.rst
+++ b/README.rst
@@ -1,1 +1,57 @@
+This CKAN Extension demonstrates some common patterns for customising a CKAN instance.
 
+It comprises:
+
+   * A CKAN Extension "plugin" at ``ckanext/example/plugin.py``
+     which, when loaded, overrides various settings in the core
+     ``ini``-file to provide:
+
+     * A path to local customisations of the core templates and stylesheets
+     * A "stream filter" that replaces arbitrary strings in rendered templates
+     * A "route" to override and extend the default behaviour of a core CKAN page
+
+   * A custom Pylons controller for overriding some core CKAN behaviour
+
+   * A custom Package edit form
+
+   * Some simple template customisations
+
+Installation
+============
+
+To install this package, from your CKAN virtualenv, run the following from your CKAN base folder (e.g. ``pyenv/``)::
+
+  pip install -e git+https://github.com/okfn/ckanext-example#egg=ckanext-example
+
+Then activate it by setting ``ckan.plugins = example`` in your main ``ini``-file.
+
+
+Orientation
+===========
+
+* Examine the source code, starting with ``ckanext/example/plugin.py``
+
+* To understand the nuts and bolts of this file, which is a CKAN
+  *Extension*, read in conjunction with the "Extension
+  documentation":http://packages.python.org/ckan/plugins.html
+
+* One thing the extension does is set the values of
+  ``extra_public_paths`` and ``extra_template_paths`` in the CKAN
+  config, which are "documented
+  here":http://packages.python.org/ckan/configuration.html#extra-template-paths
+
+* These are set to point at directories within
+  `ckanext/example/theme/`` (in this package).  Here, we override
+  the home page, provide some extra style with an ``extra.css``, and
+  customise the navigation and header of the main template in the file ``layout.html``.
+
+  The latter file is a great place to make global theme alterations.
+  It uses the _layout template_ pattern "described in the Genshi
+  documentation":http://genshi.edgewall.org/wiki/GenshiTutorial#AddingaLayoutTemplate.
+  This allows you to use Xpath selectors to override snippets of HTML
+  globally.
+
+* The custom package edit form at ``package_form.py`` follows the
+  conventions in the "main CKAN
+  documentation":http://packages.python.org/ckan/forms.html
+