diff --git a/docs/03-declarative-layout.md b/docs/03-declarative-layout.md
index 0ba6e931f..19b8479e2 100644
--- a/docs/03-declarative-layout.md
+++ b/docs/03-declarative-layout.md
@@ -424,3 +424,27 @@ Code:
 
     s.mywibox : setup (three_circle)
 
+### Instantiation rules
+
+Whenever it can, Awesome tries to be asynchronous. This can take various form
+depending on the situation. For example, the `connect_signal` method allows to
+execute code when an event arrives. `awful.screen.connect_for_each_screen` also
+allow to instantiate various elements when a new screen is added. In the later
+case, it is why some widgets are added as properties to other objects instead of
+being global variables like in previous versions of Awesome.
+
+However, there is a case where this isn't enough an another abstract widget has
+to be used. This concept is called the `widget_template` and is an optional
+property of many widgets such as the `awful.widget.taglist`,
+`awful.widget.tasklist` and `naughty.widget.box`. These templates are **table**
+using the exact same syntax as the declarative widgets, but without the
+`wibox.widget` prefix in front of the curly braces. These template represents
+future widgets that will be created by their parent widget. This is necessary
+for three reasons:
+
+ * The widget must create many instances of the template at different point in
+   time.
+ * The widget data is only partially available and other fields must be set
+   at a later time (by the parent widget).
+ * The code is highly redundant and some of the logic is delegated to the parent
+   widget to simplify everything.