--- a/README.txt
+++ b/README.txt
@@ -16,4 +16,42 @@
 
    * 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 hg+https://bitbucket.org/okfn/ckanext-exampletheme#egg=ckanext-exampletheme
+
+Then activate it by setting ``ckan.plugins = exampletheme`` in your main ``ini``-file.
+
+
+Orientation
+===========
+
+* Examine the source code, starting with ``ckanext/exampletheme/__init__.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/exampletheme/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
+