--- a/pyforge/docs/plugins.rst
+++ b/pyforge/docs/plugins.rst
@@ -1,30 +1,31 @@
-Writing Plugins for PyForge
-=====================================================================
-
-
-Writing applications that run in pyforge
----------------------------------------------------------------------
-
-TODO: Basics of app writing here. HelloWiki tutorial in the
-tutorials section.
-
-
Writing event listeners
---------------------------------------------------------------------
TODO: write about event listeners in general
-Types of event hooks you can use:
+Our event system is driven by RabbitMQ, most of which you can ignore,
+because we've simplified it down to two kinds of event listeners:
-* Immediate, best effort
-* Queue based, will be processed (eventually)
+.. image:: _static/images/amqp.png
+ :alt: App Plugins
+
+Basically you either get:
+* Immediate, best effort messages
+* Queue based messages will be processed (eventually)
+
+The pyforge platform creates a pool of queue consumers that handle messages,
+and it calls all the Reactors that are registered for that event.
+
+Or, you can ask for immediate message receipt, with now guarantee of delivery.
Writing your own WebHooks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-In general it's best to use a BusHook when writing web hooks
-because you get higher performance and you don't slow down
-the queue processing.
+There's no reason a event listener can't call out over HTTP to some web
+service...
+
+TODO: Document reactors that implement web-hooks after we write some ;)
+
Extending the pyforge markup
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~