diff --git a/README.rst b/README.rst
index 2b2a2773..a7b0e69d 100644
--- a/README.rst
+++ b/README.rst
@@ -1,19 +1,73 @@
+pluggy
+======
+|pypi| |versions| |travis| |appveyor|
 
-Plugin registration and hook calling for Python
-===============================================
+A minimalist production ready plugin system.
 
-.. image:: https://img.shields.io/pypi/v/pluggy.svg
+This is the core framework used by the `pytest`_, `tox`_, and `devpi`_ projects.
+
+Please `read the docs`_ to learn more!
+
+A definitive example
+********************
+.. code-block:: python
+
+    import pluggy
+
+    hookspec = pluggy.HookspecMarker("myproject")
+    hookimpl = pluggy.HookimplMarker("myproject")
+
+
+    class MySpec(object):
+        """A hook specification namespace.
+        """
+        @hookspec
+        def myhook(self, arg1, arg2):
+            """My special little hook that you can customize.
+            """
+
+
+    class Plugin_1(object):
+        """A hook implementation namespace.
+        """
+        @hookimpl
+        def myhook(self, arg1, arg2):
+            print("inside Plugin_1.myhook()")
+            return arg1 + arg2
+
+
+    class Plugin_2(object):
+        """A 2nd hook implementation namespace.
+        """
+        @hookimpl
+        def myhook(self, arg1, arg2):
+            print("inside Plugin_2.myhook()")
+            return arg1 - arg2
+
+
+    # create a manager and add the spec
+    pm = pluggy.PluginManager("myproject")
+    pm.add_hookspecs(MySpec)
+
+    # register plugins
+    pm.register(Plugin_1())
+    pm.register(Plugin_2())
+
+    # call our `myhook` hook
+    results = pm.hook.myhook(arg1=1, arg2=2)
+    print(results)
+
+
+.. badges
+.. |pypi| image:: https://img.shields.io/pypi/v/pluggy.svg
     :target: https://pypi.python.org/pypi/pluggy
-.. image:: https://img.shields.io/pypi/pyversions/pluggy.svg
+.. |versions| image:: https://img.shields.io/pypi/pyversions/pluggy.svg
     :target: https://pypi.python.org/pypi/pluggy
-.. image:: https://img.shields.io/travis/pytest-dev/pluggy/master.svg
+.. |travis| image:: https://img.shields.io/travis/pytest-dev/pluggy/master.svg
     :target: https://travis-ci.org/pytest-dev/pluggy
-.. image:: https://img.shields.io/appveyor/ci/pytestbot/pluggy/master.svg
+.. |appveyor| image:: https://img.shields.io/appveyor/ci/pytestbot/pluggy/master.svg
     :target: https://ci.appveyor.com/project/pytestbot/pluggy
 
-This is the core plugin system used by the `pytest`_, `tox`_, and `devpi`_ projects.
-Please `read the docs`_ to learn more!
-
 .. links
 .. _pytest:
     http://pytest.org