diff --git a/README.rst b/README.rst
index 675caad..30f590b 100644
--- a/README.rst
+++ b/README.rst
@@ -2,7 +2,13 @@
 zuul-preview
 ============
 
-A preview proxy server for zuul.
+A preview proxy server for Zuul.
+
+For example, when this http proxy is fed with a ``Host`` header in the form
+similar to ``site.167715b656ee4504baa940c5bd9f3821.openstack.preview.opendev.org``
+it proxies to the artifact 'site' of the build 167715b656ee4504baa940c5bd9f3821
+under tenant 'openstack'. The actual location is determined dynamically by querying
+a Zuul API configured by the environment variable ``$ZUUL_API_URL``.
 
 Building
 --------
@@ -20,4 +26,4 @@ Then you can build the code:
 
   autoreconf -fi
   ./configure
-  make
+  make
\ No newline at end of file