let's try to explain plainly about tools, plugins and dispatchers

2 files changed, 77 insertions, 1 deletions

diff --git a/sphinx/source/extend.rst b/sphinx/source/extend.rst
index 7138359a..27bce5c2 100644
--- a/sphinx/source/extend.rst
+++ b/sphinx/source/extend.rst
@@ -129,6 +129,7 @@ system such as provided by `zeromq <http://zeromq.org/>`_ or
 `RabbitMQ <https://www.rabbitmq.com/>`_. 
 Use it with the understanding that it may have a cost.
 
+.. _cpengine:
 
 Engine as a pubsub bus
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -604,6 +605,8 @@ page handler instead of the user id.
         def index(self, user):
             return "hello %s" % user.name
 
+.. _dispatchers:
+
 Tailored dispatchers
 ####################
 
diff --git a/sphinx/source/tutorials.rst b/sphinx/source/tutorials.rst
index 1ce94cf0..ffa26c78 100644
--- a/sphinx/source/tutorials.rst
+++ b/sphinx/source/tutorials.rst
@@ -854,5 +854,78 @@ demo, this should do.
    on each call. This is clearly not really production friendly,
    and it is probably advisable to either use a more capable
    database engine or a higher level library, such as 
-   `SQLAlchemy <http://sqlalchemy.readthedocs.org>`, to better
+   `SQLAlchemy <http://sqlalchemy.readthedocs.org>`_, to better
    support your application's needs.
+
+
+Tutorial 10: Organize my code
+#############################
+
+CherryPy comes with a powerful architecture
+that helps you organizing your code in a way that should make
+it easier to maintain and more flexible. 
+
+Several mechanisms are at your disposal, this tutorial will focus
+on the three main ones:
+
+- :ref:`dispatchers <dispatchers>`
+- :ref:`tools <tools>`
+- :ref:`plugins <busplugins>`
+
+In order to understand them, let's imagine you are at a superstore:
+
+- You have several tills and people queuing for each of them (those are your requests)
+- You have various sections with food and other stuff (these are your data)
+- Finally you have the superstore people and their daily tasks
+  to make sure sections are always in order (this is your backend)
+
+In spite of being really simplistic, this is not far from how your
+application behaves. CherryPy helps your structure your application 
+in a way that mirrors these high-level ideas.
+
+Dispatchers
+^^^^^^^^^^^
+
+Coming back to the superstore example, it is likely that you will
+want to perform operations based on the till:
+
+- Have a till for baskets with less than ten items
+- Have a till for disabled people
+- Have a till for pregnant women
+- Have a till where you can only using the store card
+
+To support these use-cases, CherryPy provides a mechanism called
+a :ref:`dispatcher <dispatchers>`. A dispatcher is executed early
+during the request processing in order to determine which piece of
+code of your application will handle the incoming request. Or, to
+continue on the store analogy, a dispatcher will decide which
+till to lead a customer to.
+
+Tools
+^^^^^
+
+Let's assume your store has decided to operate a discount spree but,
+only for a specific category of customers. CherryPy will deal
+with such use case via a mechanism called a :ref:`tool <tools>`.
+
+A tool is a piece of code that runs on a per-request
+basis in order to perform additional work. Usually a tool is a 
+simple Python function that is executed at a given point during
+the process of the request by CherryPy.
+
+Plugins
+^^^^^^^
+
+As we have seen, the store has a crew of people dedicated to manage
+the stock and deal with any customers' expectation.
+
+In the CherryPy world, this translates into having functions
+that run outside of any request life-cycle. These functions should
+take care of background tasks, long lived connections (such as
+those to a database for instance), etc. 
+
+:ref:`Plugins <busplugins>` are called that way because 
+they work along with the CherryPy :ref:`engine <cpengine>` 
+and extend it with your operations.
+
+