diff --git a/doc/source/addons.rst b/doc/source/addons.rst
index 548e8ad461d..bba57b40bd0 100644
--- a/doc/source/addons.rst
+++ b/doc/source/addons.rst
@@ -1,6 +1,10 @@
 Developing OpenERP Web Addons
 =============================
 
+An OpenERP Web addon is simply a Python package with an openerp
+descriptor (a ``__openerp__.py`` file) which follows a few structural
+and namespacing rules.
+
 Structure
 ---------
 
@@ -50,6 +54,62 @@ Structure
 ``test/``
   The directories in which all tests for the addon are located.
 
+Some of these are guidelines (and not enforced by code), but it's
+suggested that these be followed. Code which does not fit into these
+categories can go wherever deemed suitable.
+
+Namespacing
+-----------
+
+Python
+++++++
+
+Because addons are also Python packages, they're inherently namespaced
+and nothing special needs to be done on that front.
+
+JavaScript
+++++++++++
+
+The JavaScript side of an addon has to live in the namespace
+``openerp.$addon_name``. For instance, everything created by the addon
+``base`` lives in ``openerp.base``.
+
+The root namespace of the addon is a function which takes a single
+parameter ``openerp``, which is an OpenERP client instance. Objects
+(as well as functions, registry instances, etc...) should be added on
+the correct namespace on that object.
+
+The root function will be called by the OpenERP Web client when
+initializing the addon.
+
+.. code-block:: javascript
+
+    // root namespace of the openerp.example addon
+    /** @namespace */
+    openerp.example = function (openerp) {
+        // basic initialization code (e.g. templates loading)
+        openerp.example.SomeClass = Class.extend(
+            /** @lends openerp.example.SomeClass# */{
+            /**
+             * Description for SomeClass's constructor here
+             *
+             * @constructs
+             */
+            init: function () {
+                // SomeClass initialization code
+            }
+            // rest of SomeClass
+        });
+
+        // access an object in an other addon namespace to replace it
+        openerp.base.SearchView = openerp.base.SearchView.extend({
+            init: function () {
+                this._super.apply(this, arguments);
+                console.log('Search view initialized');
+            }
+        });
+    }
+
 .. _addons-testing:
 
 Testing