diff --git a/README.rst b/README.rst
index 379ca203..49a8ce49 100644
--- a/README.rst
+++ b/README.rst
@@ -1,21 +1,32 @@
 Image building tools for OpenStack
 ==================================
 
-These tools are the components of TripleO
-(https://wiki.openstack.org/wiki/TripleO) that are responsible for
-building disk images.
+``diskimage-builder`` is a flexible suite of components for building a
+wide-range of disk images, filesystem images and ramdisk images for
+use with OpenStack.
 
-This repository has the core functionality for building disk images, file
-system images and ramdisk images for use with OpenStack (both virtual and bare
-metal). The core functionality includes the various operating system specific
-modules for disk/filesystem images, and deployment and hardware inventory
-ramdisks.
+This repository has the core functionality for building such images,
+both virtual and bare metal.  Images are composed using `elements`;
+while fundamental elements are provided here, individual projects have
+the flexibility to customise the image build with their own elements.
 
-The TripleO project also develops elements that can be used to deploy
-OpenStack itself. These live in the TripleO elements repository
-(https://git.openstack.org/cgit/openstack/tripleo-image-elements).
+For example::
 
-Online documentation:
+  $ DIB_RELEASE=trusty disk-image-create -o ubuntu-trusty.qcow2 vm ubuntu
+
+will create a bootable Ubuntu Trusty based ``qcow2`` image.
+
+``diskimage-builder`` is useful to anyone looking to produce
+customised images for deployment into clouds.  These tools are the
+components of `TripleO <https://wiki.openstack.org/wiki/TripleO>`__
+that are responsible for building disk images.  They are also used
+extensively to build images for testing OpenStack itself, particularly
+with `nodepool
+<http://docs.openstack.org/infra/system-config/nodepool.html>`__.
+Platforms supported include Ubuntu, CentOS, RHEL and Fedora.
+
+Full documentation, the source of which is in ``doc/source/``, is
+published at:
 
 * http://docs.openstack.org/developer/diskimage-builder/